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Preface 



This manual is a general reference for a standard CP/M system. 
Features of Apple SoftCard III CP/M may differ slightly in features 
or operation from the system described in this manual. Consult 
your SoftCard III Installation and Operation Manual for specific 
details. 
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1 

Introduction to 

CP/M Features and Facilities 



Introduction 



CP/M is a monitor control program for microcomputer system 
development which uses IBM-compatible flexible disks for backup 
storage. Using a computer mainframe based upon Intel's 8080 
microcomputer, CP/M provides a general environment for program 
construction, storage, and editing, along with assembly and program 
check-out facilities. An important feature of CP/M is that it can be 
easily altered to execute with any computer configuration which 
uses an Intel 8080 (or Zilog Z-80) Central Processing Unit, and has 
at least 16K bytes of main memory with up to four IBM-compatible 
diskette drives. Although the standard Digital Research version 
operates on a single-density Intel MDS 800, several different 
hardware manufacturers support their own input-output drivers for 
CP/M. 

The CP/M monitor provides rapid access to programs through a 
comprehensive file management package. The file subsystem 
supports a named file structure, allowing dynamic allocation of file 
space as well as sequential and random file access. Using this file 
system, a large number of distinct programs can be stored in both 
source and machine executable form. 

CP/M also supports a powerful context editor, Intel-compatible 
assembler, and debugger subsystem. Optional software includes a 
powerful Intel-compatible macro assembler, symbolic debugger, 
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along with various high-level languages. When coupled with CP/M's 
Console Command Processor, the resulting facilities equal or excel 
similar large computer facilities. 

CP/M is logically divided into several distinct parts: 

BIOS Basic I/O System (hardware dependent) 

BDOS Basic Disk Operating System 

CCP Console Command Processor 



TPA 



Transient Program Area 



The BIOS provides the primitive operations necessary to access 
the diskette drives and to interface standard peripherals (teletype, 
CRT, Paper Tape Reader/Punch, and user-defined peripherals), and 
can be tailored by the user for any particular hardware environment 
by "patching" this portion of CP/M. 

The BDOS provides disk management by controlling one or more 
disk drives containing independent file directories. The BDOS 
implements disk allocation strategies which provide fully dynamic 
file construction while minimizing head movement across the disk 
during access. Any particular file may contain any number of 
records, not exceeding the size of any single disk. In a standard 
CP/M system, each disk can contain up to 64 distinct files. The 
BDOS has entry points which include the following primitive 
operations which can be programmatically accessed: 

SEARCH Look for a particular disk file by name. 

OPEN Open a file for further operations. 

CLOSE Close a file after processing. 

RENAME Change the name of a particular file. 

READ Read a record from a particular file. 

WRITE Write a record onto the disk. 

SELECT Select a particular disk drive for 

further operations. 
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The CCP provides symbolic interface between the user's console 
and the remainder of the CP/M system. The CCP reads the console 
device and processes commands which include listing the file 
directory, printing the contents of files, and controlling the operation 
of transient programs, such as assemblers, editors, and debuggers. 
The standard commands which are available in the CCP are listed 
in a following section. 

The last segment of CP/M is the area called the Transient Program 
Area (TPA). The TPA holds programs which are loaded from the 
disk under command of the CCP. During program editing, for 
example, the TPA holds the CP/M text editor machine code and 
data areas. Similarly, programs created under CP/M can be checked 
out by loading and executing these programs in the TPA. 

It should be mentioned that any or all of the CP/M component 
subsystems can be "overlayed" by an executing program. That is, 
once a user's program is loaded into the TPA, the CCP, BDOS, and 
BIOS areas can be used as the program's data area. A "bootstrap" 
loader is programmatically accessible whenever the BIOS portion 
is not overlayed; thus, the user program need only branch to the 
bootstrap loader at the end of execution, and the complete CP/M 
monitor is reloaded from disk. 

It should be reiterated that the CP/M operating system is partitioned 
into distinct modules, including the BIOS portion which defines the 
hardware environment in which CP/M is executing. Thus, the 
standard system can be easily modified to any non-standard 
environment by changing the peripheral drivers to handle the 
custom system. 



An Overview of CP/M 2.0 Facilities 



CP/M 2.0 is a high-performance single-console operating system 
which uses table driven techniques to allow field configuration to 
match a wide variety of disk capacities. All of the fundamental file 
restrictions are removed, while maintaining upward compatibility 
from previous versions of release 1 . Features of CP/M 2.0 include 
field specification of one to sixteen logical drives, each containing 
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up to eight megabytes. Any particular file can reach the full drive 
size with the capability to expand to thirty-two megabytes in future 
releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged 
with read/only and system attributes. Users of CP/M 2.0 are 
physically separated by user numbers, with facilities for file copy 
operations from one user area to another. Powerful relative-record 
random access functions are present in CP/M 2.0 which provide 
direct access to any of the 65536 records of an eight megabyte file. 

All disk-dependent portions of CP/M 2.0 are placed into a BIOS- 
resident "disk parameter block" which is either hand coded or 
produced automatically using the disk definition macro library 
provided with CP/M 2.0. The end user need only specify the 
maximum number of active disks, the starting and ending sector 
numbers, the data allocation size, the maximum extent of the 
logical disk, directory size information, and reserved track values. 
The macros use this information to generate the appropriate tables 
and table references for use during CP/M 2.0 operation. Deblocking 
information is also provided which aids in assembly or disassembly 
of sector sizes which are multiples of the fundamental 128 byte 
data unit, and the system alteration manual includes general-purpose 
subroutines which use this deblocking information to take advantage 
of larger sector sizes. Use of these subroutines, together with the 
table driven data access algorithms, make CP/M 2.0 truly a universal 
data management system. 

File expansion is achieved by providing up to 512 logical file 
extents, where each logical extent contains 16K bytes of data. 
CP/M 2.0 is structured, however, so that as much as 1 28K bytes of 
data is addressed by a single physical extent (corresponding to a 
single directory entry), thus maintaining compatibility with previous 
versions while taking full advantage of directory space. 

Random access facilities are present in CP/M 2.0 which allow 
immediate reference to any record of an eight megabyte file. Using 
CP/M's unique data organization, data blocks are only allocated 
when actually required and movement to a record position requires 
little search time. Sequential file access is upwardly compatible 
from earlier versions to the full eight megabytes, while random 
access compatibility stops at 51 2K byte files. Due to CP/M 2.0's 
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simpler and faster random access, application programmers are 
encouraged to alter their programs to take full advantage of the 2.0 
facilities. 

Several CP/M 2.0 modules and utilities have improvements which 
correspond to the enhanced file system. STAT and PIP both account 
for file attributes and user areas, while the CCP provides a "login" 
function to change from one user area to another. The CCP also 
formats directory displays in a more convenient manner and 
accounts for both CRT and hard-copy devices in its enhanced line 
editing functions. 



Functional Description of CP/M 



The user interacts with CP/M primarily through the CCP, which 
reads and interprets commands entered through the console. In 
general, the CCP addresses one of several disks which are online 
(the standard system addresses up to four different disk drives). 
These disk drives are labelled A, B, C, and D. A disk is "logged in" if 
the CCP is currently addressing the disk. In order to clearly 
indicate which disk is the currently logged disk, the CCP always 
prompts the operator with the disk name followed by the symbol 
">" indicating that the CCP is ready for another command. Upon 
initial start up, the CP/M system is brought in from disk A, and 
the CCP displays the message 

xxKCP/M VER m.m 

where xx is the memory size (in kilobytes) which this CP/M system 
manages, and m.m is the CP/M version number. Following system 
signon, CP/M automatically logs in disk A, prompts the user with 
the symbol "A>" (indicating that CP/M is currently addressing 
disk "A"), and waits for a command. The commands are implemented 
to two levels: built-in commands and transient commands. 
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General Command Structure 



Built-in commands are a part of the CCP program itself, while 
transient commands are loaded into the TPA from disk and 
executed. The built-in commands are 

ERA Erase specified files. 

DIR Displays file names in the directory. 

REN Rename the specified file. 

SAVE Save memory contents in a file. 

TYPE Type the contents of a file on the logged disk. 

USER Move to another area within the same 

directory. 

Nearly all of the commands reference a particular file or group of 
files. The form of a file reference is specified below. 



File References 



A file reference identifies a particular file or group of files on a 
particular disk attached to CP/M. These file references can be 
either "unambiguous" (ufn) or "ambiguous" (afn). An unambiguous 
file reference uniquely identifies a single file, while an ambiguous 
file reference may be satisfied by a number of different files. 

File references consist of two parts: the primary name and the 
secondary name. Although the secondary name is optional, it 
usually is generic; that is, the secondary name "ASM," for 
example, is used to denote that the file is an assembly language 
source file, while the primary name distinguishes each particular 
source file. The two names are separated by a "." as shown below: 

pppppppp.sss 

Where pppppppp represents the primary name of eight characters 
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or less, and sss is the secondary name of no more than three 
characters. As mentioned above, the name 

pppppppp 

is also allowed and is equivalent to a secondary name consisting 
of three blanks. The characters used in specifying an unambiguous 
file reference cannot contain any of the special characters 



<> 



[] 



while all alphanumerics and remaining special characters are 
allowed. 

An ambiguous file reference is used for directory search and 
pattern matching. The form of an ambiguous file reference is 
similar to an unambiguous reference, except the symbol "?" may 
be interspersed throughout the primary and secondary names. In 
various commands throughout CP/M, the "?" symbol matches any 
character of a file name in the "?" position. Thus, the ambiguous 
reference 

X?Z.C?M 
is satisfied by the unambiguous file names 

XYZ.COM 
and 

X3Z.CAM 
Note that the ambiguous reference 



is equivalent to the ambiguous file reference 
???????? ??? 
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while 

pppppppp.* 
and 

*.sss 
are abbreviations for 

pppppppp.??? 
and 

.????????. sss 
respectively. As an example, 

DIR*.* 

is interpreted by the CCP as a command to list the names of all disk 
files in the directory, while 

DIRX.Y 

searches only for a file by the name X.Y. Similarly, the command 

DIRX?YC?M 

causes a search for all (unambiguous) file names on the disk which 
satisfy this ambiguous reference. 

The following file names are valid unambiguous file references: 



X 
X.Y 



XYZ 
XYZ.COM 



GAMMA 
GAMMA.1 



As an added convenience, the programmer can generally specify 
the disk drive name along with the file name. In this case, the drive 
name is given as a letter A through Z followed by a colon (:). The 
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specified drive is then "logged in" before the file operation occurs. 
Thus, the following are valid file names with disk name prefixes: 



A:X.Y 
Z:XYZ.COM 



B:XYZ 
B:X.A?M 



C:GAMMA 
C:*.ASM 



It should also be noted that all alphabetic lower case letters in file 
and drive names are always translated to upper case when they 
are processed by the CCP. 



Switching Disks 



The operator can switch the currently logged disk by typing the 
disk drive name (A, B, C, or D) followed by a colon (:) when the CCP 
is waiting for console input. Thus, the sequence of prompts and 
commands shown below might occur after the CP/M system is 
loaded from disk A: 



16KCP/M VER 1.4 
A>DIR 

SAMPLE ASM 
SAMPLE PRN 
A>B: 

B>Dir*.ASM 
DUMP ASM 

FILES ASM 

B>A: 



List all files on disk A. 



Switch to disk B. 

List all ASM" files on B. 



Switch back to A. 



Form of Buiit-in Commands 



The file and device reference forms described above can now be 
used to. fully specify the structure of the built-in commands. In the 
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description below, assume the following abbreviations: 
ufn unambiguous file reference 



afn 
cr 



ambiguous file reference 
carriage return 



Further, recall that the CCP always translates lower case characters 
to upper case characters internally. Thus, lower case alphabetics 
are treated as if they are upper case in command names and file 
references. 

ERAse Command 

ERA afn 

The ERA (erase) command removes files from the currently 
logged-in disk (i.e., the disk name currently prompted by CP/M 
preceding the ">"). The files which are erased are those which 
satisfy the ambiguous file reference afn. The following examples 
illustrate the use of ERA: 



ERAX.Y 

ERAX.* 
ERA*.ASM 
ERA X?Y.C?M 

ERA*.* 



The file named X.Y on the currently 
logged disk is removed from the disk 
directory, and the space is returned. 

All files with primary name X are 
removed from the current disk. 

All files with secondary name ASM 
are removed from the current disk. 

All files on the current disk which 
satisfy the ambiguous reference 
X?YC?M are deleted. 

Erase all files in the current user's 
directory. (See USER, page 15.) The 
CCP prompts with the message 

ALL(Y/N)? 

which requires a Y response before 
files are actually removed. 
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ERA B:*.PRN All files on drive B which satisfy 

the ambiguous reference 

????????. PRN 

are deleted, independently of the 
currently logged disk. 

Dl Rectory Command 

DIRafn 

The DIR(directory) command causes the names of all files which 
satisfy the ambiguous file name afn to be listed at the console 
device. As a special case, the command 

DIR 

lists the files on the currently logged disk (the command "DIR" is 
equivalent to the command "DIR *.*"). Valid DIR commands are 
shown below. 

DIRX.Y 
DIRX?Z.C?M 
DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a 
drive name. The following DIR commands cause the selected 
drive to be addressed before the directory search takes place. 



DIRB 
DIR B 
DIR B 



X.Y 
*.A?M 



If no files can be found on the selected diskette which satisfy the 
directory request, then the message "NOT FOUND" is typed at 
the console. 
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REName Command 



REN ufn2 = ufn1 



The REN (rename) command allows the user to change the 
names of files on disk. The file satisfying ufn2 is changed to ufnl . 
The currently logged disk is assumed to contain the file to 
rename (ufnl ). The CCP also allows the user to type a left-directed 
arrow instead of the equal sign, if the user's console supports the 
graphic character. Examples of the REN command are 



RENX.Y = Q.R 

REN XYZ.COM = XYZ.XXX 



The file Q.R is changed 
to X.Y. 

The file XYZ.XXX is 
changedtoXYZ.COM. 



The operator can precede either ufnl or ufn2 (or both) by an 
optional drive address. Given that ufnl is preceded by a drive 
name, then ufn2 is assumed to exist on the same drive as ufnl . 
Similarly, if ufn2 is preceded by a drive name, then ufnl is assumed 
to reside on that drive as well. If both ufnl and ufn2 are preceded 
by drive names, then the same drive must be specified in both 
cases. The following REN commands illustrate this format. 



REN A:X.ASM=YASM 



REN B:ZARBAS = ZOT.BAS 



REN B:A.ASM = B:A.BAK 



The file Y.ASM is 
changed to X.ASM on 
drive A. 

The file ZOT.BAS is 
changed to ZAP.BAS on 
drive B. 

ThefileA.BAKis 
renamed to A. ASM on 
drive B. 



If the file ufnl is already present, the REN command will respond 
with the error "FILE EXISTS" and not perform the change. If 
ufn2 does not exist on the specified diskette, then the message 
"NOT FOUND" is printed at the console. 
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SAVE Command 

SAVE n ufn 

The SAVE command places n pages (256-byte blocks) onto disk 
from the TPA and names this file ufn. In the CP/M distribution 
system, the TPA starts at 100H (hexadecimal), which is the 
second page of memory. Thus, if the user's program occupies the 
area from 100H through 2FFH, the SAVE command must specify 
two pages of memory. The machine code file can be subsequently 
loaded and executed. Examples are: 



SAVE 3 X.COM 



SAVE 40 Q 



SAVE 4 X.Y 



Copies 100H through 
3FFHtoX.COM. 

Copies 100H through 
28FFH to Q (note that 
28 is the page count in 
28FFH, and that 28H = 
2*16+8 = 40 decimal). 

Copies 100H through 
4FFH to X.Y. 



The SAVE command can also specify a disk drive in the afn portion 
of the command, as shown below. 



SAVE 10 B:ZOT.COM 



Copies 10 pages (100H 
through OAFFH) to the 
file ZOT.COM on drive B. 



The SAVE operation can be used any number of times without 
altering the memory image. 

TYPE Command 

TYPE ufn 



The TYPE command displays the contents of the ASCII source file 
ufn on the currently logged disk at the console device. Valid 
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TYPE commands are 

TYPE X.Y 
TYPE X.PLM 
TYPE XXX 

The TYPE command expands the tabs (ctl-l characters), assuming 
tab positions are set at every eighth column. The ufn can also 
reference a drive name as shown below. 



TYPE B:X.PRN 



The file X.PRN from 
drive B is displayed. 



USER Command 



USER n 



Where n is an integer value in the range to 15. 

Upon cold start, the operator is automatically "logged" into user 
area number 0. The operator may issue the USER command at any 
time to move to another logical area within the same directory. 

Drives which are logged in while addressing one user number 
are automatically active when the operator moves to another user 
number since a user number is simply a prefix which accesses 
particular directory entries on the active disks. 

The active user number is maintained until changed by a subsequent 
USER command, or until a cold start operation when user is 
again assumed. 



Line Editing and Output Control 



The CCP allows certain line editing functions while typing command 
lines. "Control" indicates that the Control key and the indicated key 
are to be pressed simultaneously. CCP commands can generally be 
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up to 255 characters in length; they are not acted upon until the 
carriage return key is pressed. 



rubout/delete 
Control C 
Control E 

Control H 



Control J 
Control M 
Control R 

Control X 



Remove and echo last character typed. 

Reboot CP/M when at beginning of line. 

Physical end of line: carriage is 
returned, but line is not sent until the 
carriage return key is depressed. 

Backspace one character position. 
Produces the backspace overwrite 
function. Can be changed internally 
to another character, such as delete, 
through a simple single byte change. 

Line feed. Terminates current input. 

Carriage return. Terminates input. 

Retype current command line after 
new line. 

Backspace to beginning of current line. 



The line editor keeps track of the current prompt column position 
so that the operator can properly align data input following a 
Control R or Control X command. 

The control functions Control P and Control S affect console output 
as shown below. 



Control P 



Control S 



Copy all subsequent console output 
to the currently assigned list device 
(see the STAT command). Output is sent 
to both the list device and the console 
device until the next Control P is typed. 

Stop the console output temporarily. 
Program execution and output continue 
when the next character is typed at 
the console (e.g., another Control S). 
This feature is used to stop output on 
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high speed consoles, such as CRT's, 
in order to view a segment of output 
before continuing. 



Transient Commands 



Transient commands are loaded from the currently logged disk and 
executed in the TPA. The transient commands defined for execution 
under the CCP are shown below. Additional functions can easily be 
defined by the user (see the LOAD command definition). 



STAT 



ASM 



LOAD 



DDT 
PIP 

ED 

SUBMIT 

DUMP 



List the number of bytes of storage 
remaining on the currently logged disk, 
provide statistical information about 
particular files, and display or alter 
device assignment. 

Load the CP/M assembler and 
assemble the specified program from 
disk. 

Load the file in Intel "hex" machine 
code format and produce a file in 
machine executable form which can be 
loaded into the TPA (this loaded 
program becomes a new command 
under the CCP). 

Load the CP/M debugger into TPA 
and start execution. 

Load the Peripheral Interchange 
Program for subsequent disk file and 
peripheral transfer operations. 

Load and execute the CP/M text 
editor program. 

Submit a file of commands for 
batch processing. 

Dump the contents of a file in hex. 
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Transient commands are specified in the same manner as built-in 
commands, and additional commands can be easily defined by the 
user. As an added convenience, the transient command can be 
preceded by a drive name, which causes the transient to be loaded 
from the specified drive into the TPA for execution. Thus, the 
command 

B:STAT 

causes CP/M to temporarily "log in" drive B for the source of the 
STAT transient, and then return to the original logged disk for 
subsequent processing. 

The basic transient commands are listed in detail below. 

STAT 

The STAT command provides general statistical information about 
file storage and device assignment. It is initiated by typing one of 
the following forms: 



STAT 
STAT' 



command line" 



Special forms of the "command line" allow the current device 
assignment to be examined and altered as well. The various 
command lines which can be specified are shown below, with an 
explanation of each form shown to the right. 



STAT <cr> 



If the user types an empty command 
line, the STAT transient calculates the 
storage remaining on all active drives, 
and prints a message 



or 



x: R/W, SPACE: nnnK 
x: R/O, SPACE: nnnK 



for each active drive x, where R/W 
indicates the drive may be read or 
written, and R/O indicates the drive 
is read only (a drive becomes R/O by 
explicitly setting it to read only, as 
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STAT x: <cr> 



STAT afn <cr> 



STAT x:afn <cr> 



shown below, or by inadvertently changing 
diskettes without performing a warm 
start). The space remaining on the 
diskette in drive x is given in kilobytes 
by nnn. 

If a drive name is given, then the drive 
is selected before the storage is 
computed. Thus, the command "STAT B:" 
could be issued while logged into drive 
A, resulting in the message 

BYTES REMAINING ON B: nnnK 

The command line can also specify a set 
of files to be scanned by STAT. The files 
which satisfy afn are listed in alphabetical 
order, with storage requirements for each 
file under the heading 



RECS BYTS 
rrrr bbbK 



EX D:FILENAME.TYP 

ee d:pppppppp.sss 



where rrrr is the number of 128-byte 
records allocated to the file, bbb is the 
number of kilobytes allocated to the file 
(bbb=rrrr*1 28/1 024), ee is the number of 
16K extensions (ee=bbb/16), d is the 
drive name containing the file (A...Z), 
pppppppp is the (up to) eight-character 
primary file name, and sss is the 
(up to) three-character secondary name. 
After listing the individual files, the 
storage usage is summarized. 

As a convenience, the drive name can 
be given ahead of the afn. In this case, 
the specified drive is first selected, and 
the form "STAT afn" is executed. 
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STAT d:filename.typ $S<cr> 



("d:" is optional drive 
name and 
"filename. typ" is 
an unambiguous or 
ambiguous file 
name) 



Produces the output display format: 
Size Recs Bytes Ext Ace 



48 

55 

65536 


48 

55 

128 


6K 

12K 

2K 


1 R/OA:ED.COM 

1 R/0(A:PIRCOM) 

2 R/WA:X.DAT 



The $S parameter causes the "Size" 
field to be displayed. (The command 
may be used without the $S if desired.) 
The Size field lists the virtual file size 
in records, while the "Recs" field sums 
the number of virtual records in each 
extent. For files constructed sequentially, 
the Size and Recs fields are identical. 
The "Bytes" field lists the actual number 
of bytes allocated to the corresponding 
file. The minimum allocation unit is 
determined at configuration time, and 
thus the number of bytes corresponds to 
the record count plus the remaining 
unused space in the last allocated 
block for sequential files. Random access 
files are given data areas only when 
written, so the Bytes field contains the 
only accurate allocation figure. In the 
case of random access, the Size field 
gives the logical end-of-file record 
position and the Recs field counts the 
logical records of each extent (each of 
these extents, however, may contain 
unallocated "holes" even though they 
are added into the record count). The 
"Ext" field counts the number of local 
16K extents allocated to the file. The 
"Ace" field gives the R/O or R/W access 
mode, which is changed using the 
commands shown below. The parentheses 
shown around the PIP.COM file name 
indicate that it has the "system" 
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indicator set, so that it will not be 
listed in DIR commands. 

STAT d:filename.typ $R/0 <cr> 

Places the file or set of files in a 
read-only status until changed by a 
subsequent STAT command. The R/O 
status is recorded in the directory with the 
file so that it remains R/O through 
intervening cold start operations. When a 
file is marked R/O, attempts to erase or 
write into the file result in a terminal BDOS 
message: Bdos Err on D: File R/O. 

STAT d:filename.typ $R/W <cr> 

Places the file in a permanent 
read/write status. 

STAT d:filename.typ $SYS <cr> 

Attaches the system indicator to the file. 

STATd.filename.typ $DIR <cr> 

Removes the system indicator from the file. 



STATd:DSK:<cr> 



Lists the drive characteristics of the disk 
named by "d:" which is in the range 

A:, B: P:. The drive characteristics 

are listed in the format: 



d 

65536 

8192 

128 



1024 

128 

58 

2 



Drive Characteristics 
128 Byte Record Capacity 
Kilobyte Drive Capacity 
32 Byte Directory Entries 
Checked Directory Entries 
Records/Extent 
Records/Block 
Sectors/Track 
Reserved Tracks 



The total record capacity is listed, followed 
by the total drive capacity listed in Kbytes. 
The number of checked entries is usually 
identical to the directory size for removable 
media, since this mechanism is used to 
detect changed media during CP/M 
operation without an intervening warm 
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STAT DSK: <cr:; 
STAT USR: <cr; 



start. The number of records per extent 
determines the addressing capacity of 
each directory entry (1024 times 128 bytes, 
or 128K in the example above). The 
number of records per block shows the 
basic allocation size (in the example, 128 
records/block times 128 bytes per record, 
or 16K bytes per block). The listing is then 
followed by the number of physical sectors 
per track and the number of reserved 
tracks. 

Lists drive characteristics as above for all 
currently active drives. 

Produces a list of the user numbers which 
have files on the currently addressed disk. 
The display format is: 

Active User: 
Active Files: 1 3 

where the first line lists the currently 
addressed user number, as set by the last 
CCP USER command, followed by a list of 
user numbers scanned from the current 
directory. In the above case, the active 
user number is (default at cold start), 
with three user numbers which have active 
files on the current disk. The operator can 
subsequently examine the directories of 
the other user numbers by logging in with 
USER 1 , USER 2, or USER 3 commands, 
followed by a DIR command at the CCP 
level. 



The STAT command also allows control over the physical to logical 
device assignment (see the IOBYTE function described in the 
"CP/M Interface Guide"). In general, there are four logical peripheral 
devices which are, at any particular instant, each assigned to one of 
several physical peripheral devices. The four logical devices are 
named: 



CON: 



The system console device (used by CCP 
for communication with the operator) 
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RDR: 
PUN: 
LST: 



The paper tape reader device 
The paper tape punch device 
The output list device 



The actual devices attached to any particular computer system are 
driven by subroutines in the BIOS portion of CP/M. Thus, the 
logical RDR: device, for example, could actually be a high speed 
reader, Teletype reader, or cassette tape. In order to allow some 
flexibility in device naming and assignment, several physical devices 
are defined, as shown below: 



TTY: 
CRT: 

BAT: 

UC1: 

PTR: 

UR1: 

UR2: 

PTP: 

UP1: 

UP2: 

LPT: 

UL1: 



Teletype device (slow speed console) 

Cathode ray tube device 
(high speed console) 

Batch processing (console is current 
RDR:, output goes to current LST: device) 

User-defined console 

Paper tape reader (high speed reader) 

User-defined reader #1 

User-defined reader #2 

Paper tape punch (high speed punch) 

User-defined punch #1 

User-defined punch #2 

Line printer 

User-defined list device #1 



It must be emphasized that the physical device names may or may 
not actually correspond to devices which the names imply. That is, 
the PTP: device may be implemented as a cassette write operation, 
if the user wishes. The exact correspondence and driving subroutine 
is defined in the BIOS portion of CP/M. 
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The command: 

STAT VAL: <cr> 

produces a summary of the available status commands, resulting in 
the output: 



Temp R/O Disk: 


d: = R/O 






Set Indicator: 


d:filename.typ $R/0 $R/W $SYS $DIR 


Disk Status: 


DSK: 


d:DSK: 




User Status: 


USR: 






lobyte Assign: 








CON. =TTY 




CRT: 


BAT: 


UC1: 


RDR: = TTY 




PTR: 


UR1: 


UR2: 


PUN: =TTY 




PTP: 


UP1: 


UP2: 


LST: =TTY 




CRT: 


LPT: 


UL1: 



In each case, the logical device shown to the left can take any of 
the four physical assignments shown to the right on each line. The 
current logical to physical mapping is displayed by typing the 
command 

STAT DEV: <cr> 

which produces a listing of each logical device to the left, and the 
current corresponding physical device to the right. For example, 
the list might appear as follows: 



CON 
RDR 
PUN 
LST: 



= CRT: 

= UR1: 

= PTP: 

TTY: 



The current logical to physical device assignment can be changed by 
typing a STAT command of the form 

STAT Id1 = pd1 , Id2 = pd2 Idn = pdn <cr> 

where Id1 through Idn are logical device names, and pd1 through 
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pdn are compatible physical device names (i.e., Idi and pdi appear on 
the same line in the "VAL:" command shown above). The 
following are valid STAT commands which change the current logical 
to physical device assignments: 



STAT CON: 
STAT PUN: 



= CRT: <cr: 
-TTY:, LST: 



LPT:,RDR: = TTY:<cr 



ASM ufn 

The ASM command loads and executes the CP/M 8080 assembler. 
The ufn specifies a source file containing assembly language 
statements where the secondary name is assumed to be ASM, and 
thus is not specified. The following ASM commands are valid: 

ASMX 

ASM GAMMA 

The two-pass assembler is automatically executed. If assembly 
errors occur during the second pass, the errors are printed at the 
console. 



The assembler produces a file 

x.PRN 

where x is the primary name specified in the ASM command. The 
PRN file contains a listing of the source program (with imbedded 
tab characters if present in the source program), along with the 
machine code generated for each statement and diagnostic error 
messages, if any. The PRN file can be listed at the console using 
the TYPE command, or sent to a peripheral device using PIP 
(see the PIP command structure below). Note also that the PRN file 
contains the original source program, augmented by 
miscellaneous assembly information in the leftmost 16 columns 
(program addresses and hexadecimal machine code, for example). 
Thus, the PRN file can serve as a backup for the original source 
file: if the source file is accidentally removed or destroyed, the 
PRN file can be edited (see the ED operator's guide) by removing 
the leftmost 16 characters of each line (this can be done by issuing 
a single editor "macro" command). The resulting file is identical 
to the original source file and can be renamed (REN) from PRN to 
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ASM for subsequent editing and assembly. The file 
x.HEX 

is also produced which contains 8080 machine language in Intel 
"hex" format suitable for subsequent loading and execution (see 
the LOAD command). For complete details of CP/M's assembly 
language program, see the "CP/M Assembler Language (ASM) 
User's Guide." 

Similar to other transient commands, the source file for assembly 
can be taken from an alternate disk by prefixing the assembly 
language file name by a disk drive name. Thus, the command 

ASM B:ALPHA<cr> 

loads the assembler from the currently logged drive and operates 
upon the source program ALPHA.ASM on drive B. The HEX and 
PRN files are also placed on drive B in this case. 

LOAD ufn cr 

The LOAD command reads the file ufn, which is assumed to 
contain "hex" format machine code, and produces a memory 
image file which can be subsequently executed. The file name ufn 
is assumed to be of the form 

x.HEX 

and thus only the name x need be specified in the command. 
The LOAD command creates a file named 

x.COM 

which marks it as containing machine executable code. The file is 
actually loaded into memory and executed when the user types 
the file name x immediately after the prompting character ">" 
printed by the CCP 

In general, the CCP reads the name x following the prompting 
character and looks for a built-in function name. If no function 
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name is found, the CCP searches the system disk directory for a 
file by the name 

x.COM 

If found, the machine code is loaded into the TPA, and the 
program executes. Thus, the user need only LOAD a hex file once, 
it can be subsequently executed any number of times by simply 
typing the primary name. In this way, the user can "invent new 
commands in the CCP. (Initialized disks contain the transient 
commands as COM files, which can be deleted at the user s 
option.) The operation can take place on an alternate drive if the 
file name is prefixed by a drive name. Thus 

LOAD B:BETA 

brings the LOAD program into the TPA from the currently logged 
disk and operates upon drive B after execution begins. 

It must be noted that the BETA.HEX file must contain valid Intel 
format hexadecimal machine code records (as produced by the 
ASM program, for example) which begin at 100H, the beginning 
of the TPA. Further, the addresses in the hex records must be in 
ascending order; gaps in unfilled memory regions are filled with 
zeroes by the LOAD command as the hex records are read. Thus, 
LOAD must be used only for creating CP/M standard ' COM files 
which operate in the TPA. Programs which occupy regions of 
memory other than the TPA can be loaded under DDT. 



PIP 

PIP is the CP/M Peripheral Interchange Program which implements 
the basic media conversion operations necessary to load, print 
punch, copy, and combine disk files. The PIP program is initiated by 
typing one of the following forms 

PIP<cr> 

PIP "command line" <cr> 

In both cases, PIP is loaded into the TPA and executed. In case 1 , 
PIP reads command lines directly from the console, prompted 
with the "*" character, until an empty command line is typed (i.e., a 
single carriage return is issued by the operator). Each successive 
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command line causes some media conversion to take place 
according to the rules shown below. Form 2 of the PIP command 
is equivalent to the first, except that the single command line given 
with the PIP command is automatically executed, and PIP 
terminates immediately with no further prompting of the console 
for input command lines. The form of each command line is 

destination = source #1 , source #2, ..., source #n <cr> 

where "destination is the file or peripheral device to receive the 
data, and "source #1 , ..., source #n" represents a series of one or 
more files or devices which are copied from left to right to the 
destination. 

When multiple files are given in the command line (i.e., n>1 ), the 
individual files are assumed to contain ASCII characters, with an 
assumed CP/M end-of-file character (ctl-Z) at the end of each file 
(see the O parameter to override this assumption). The equal 
symbol (=) can be replaced by a left-oriented arrow, if your console 
supports this ASCII character, to improve readability. Lower case 
ASCII alphabetics are internally translated to upper case to be 
consistent with CP/M file and device name conventions. Finally, 
the total command line length cannot exceed 255 characters (ctl-E 
can be used to force a physical carriage return for lines which 
exceed the console width). 

The destination and source elements can be unambiguous 
references to CP/M source files, with or without a preceding disk 
drive name. That is, any file can be referenced with a preceding 
drive name (A:, B:, C:, or D:) which defines the particular drive 
where the file may be obtained or stored. When the drive name 
is not included, the currently logged disk is assumed. Further, the 
destination file can also appear as one or more of the source 
files, in which case the source file is not altered until the entire 
concatenation is complete. If the destination file already exists, it 
is removed if the command line is properly formed (it is not 
removed if an error condition arises). The following command 
lines (with explanations to the right) are valid as input to PIP: 



X = Y <cr> 



Copy to file X from file Y, where 
X and Y are unambiguous file 
names; Y remains unchanged. 



Introduction 



X = Y,Z <cr> 



Concatenate files Y and Z and 
copy to file X, with Y and 
Z unchanged. 



X.ASM = Y.ASM,Z.ASM,FIN.ASM <cr> 

Create the file X.ASM from the 
concatenation of the Y, Z, and 
FIN files with type ASM. 



NEW.ZOT= B:OLD.ZAP<cr> 



B:A.U. = B:B.V,A:C.W,D.X<cr> 



Move a copy of OLD. ZAP from 
drive B to the currently logged 
disk; name the file NEW.ZOT 

Concatenate file B.V from drive 
B with C.W from drive A and 
D.X. from the logged disk; 
create the file A. U on 
drive B. 



For more convenient use, PIP allows abbreviated commands for 
transferring files between disk drives. The abbreviated forms are 

PIPx: = afn<cr> 
PIPx: = y:afn<cr> 
PIPufn = y:<cr> 
PIPx:ufn = y:<cr> 

The first form copies all files from the currently logged disk 
which satisfy the afn to the same file names on drive x (x = A...Z). 
The second form is equivalent to the first, where the source for 
the copy is drive y (y = A...Z). The third form is equivalent to the 
command "PIP ufn = y:ufn <cr>" which copies the file given by 
ufn from drive y to the file ufn on drive x. The fourth form is 
equivalent to the third, where the source disk is explicitly given 
byy. 

Note that the source and destination disks must be different in 
all of these cases. If an afn is specified, PIP lists each ufn which 
satisfies the afn as it is being copied. If a file exists by the same 
name as the destination file, it is removed upon successful 
completion of the copy, and replaced by the copied file. 
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The following PIP commands give examples of valid disk-to-disk 
copy operations: 



B: = *.COM<cr> 

A: = B:ZAR*<cr> 

ZAP.ASM = B:<cr> 
B:ZOT.COM = A:<cr> 
B: = GAMMA.BAS<cr> 
B: = A:GAMMA.BAS<cr> 



Copy all files which have the 
secondary name "COM" to drive 
B from the current drive. 

Copy all files which have the 
primary name "ZAP" to drive 
A from drive B. 

Equivalent to 
ZAPASM = B:ZAPASM 

Equivalent to 
B:ZOT.COM = A:ZOT.COM 



Same as 
B:GAMMA.BAS 



GAMMA.BAS 



Same as 

B:GAMMA.BAS = A:GAMMA.BAS 



PIP also allows reference to physical and logical devices which are 
attached to the CP/M system. The device names are the same as 
given under the STAT command, along with a number of specially 
named devices. The logical devices given in the STAT command are 

CON: (console), RDR: (reader), PUN: (punch), and LST: (list) 

while the physical devices are 

TTY: (console, reader, punch, or list) 
CRT: (console, or list), UC1 : (console) 

PTR: (reader), UR1: (reader), UR2: (reader) 

PTP: (punch), UP1: (punch), UP2: (punch) 

LPT: (list), UL1: (list) 

(Note that the "BAT:" physical device is not included, since this 
assignment is used only to indicate that the RDR: and LST: devices 
are to be used for console input/output.) 

The RDR, LST, PUN, and CON devices are all defined within the 
BIOS portion of CP/M. (The current physical device mapping is 
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defined by IOBYTE; see the "CP/M Interface Guide" for a 
discussion of this function.). The destination device must be capable 
of receiving data (i.e., data cannot be sent to the punch), and the 
source devices must be capable of generating data (i.e., the LST: 
device cannot be read). 

The additional device names which can be used in PIP commands 
are 

NUL: Send 40 "nulls" (ASCII 0's) to the device (this 
can be issued at the end of punched output). 

EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the 

destination device (sent automatically at the end 
of all ASCII data transfers through PIP). 

INP: Special PIP input source which can be "patched" 

into the PIP program itself: PIP gets the input data 
character-by-character by CALLing location 
103H, with data returned in location 109H (parity 
bit must be zero). 

OUT: Special PIP output destination which can be 

patched into the PIP program: PIP CALLs location 
106H with data in register C for each character 
to transmit. Note that locations 109H through 
1 FFH of the PIP memory image are not used and 
can be replaced by special purpose drivers 
using DDT (see the DDT operator's manual). 

PRN: Same as LST:, except that tabs are expanded 
at every eighth character position, lines are 
numbered, and page ejects are inserted every 
60 lines, with an initial eject (same as [t8np]). 

File and device names can be interspersed in the PIP commands. 
In each case, the specific device is read until end-of-file (ctl-Z for 
ASCII files, and a real end of file for non-ASCII disk files). Data 
from each device or file is concatenated from left to right until 
the last data source has been read. The destination device or file is 
written using the data from the source files, and an end-of-file 
character (ctl-Z) is appended to the result for ASCII files. Note that 
if the destination is a disk file, a temporary file is created ($$$ 
secondary name) which is changed to the actual file name only 
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upon successful completion of the copy. Files with the extension 
"COM" are always assumed to be non-ASCII. 

The copy operation can be aborted at any time by depressing any 
key on the keyboard (a rubout suffices). PIP will respond with the 
message "ABORTED" to indicate that the operation was not 
completed. Note that if any operation is aborted, or if an error 
occurs during processing, PIP removes any pending commands 
which were set up while using the SUBMIT command. 

It should also be noted that PIP performs a special function if the 
destination is a disk file with type "HEX" (an Intel hex formatted 
machine code file), and the source is an external peripheral 
device, such as a paper tape reader. In this case, the PIP program 
checks to ensure that the source file contains a properly formed 
hex file, with legal hexadecimal values and checksum records. 
When an invalid input record is found, PIP reports an error 
message at the console and waits for corrective action. For 
convenience, PIP allows the end-of-file to be entered from the 
console if the source file is a RDR: device. In this case, the PIP 
program reads the device and monitors the keyboard. If ctl-Z is 
typed at the keyboard, then the read operation is terminated 
normally. 

Valid PIP commands are shown below. 



PIPLST: = X.PRN<cr> 



PIP<cr> 



Copy X.PRN to the LST device and 
terminate the PIP program. 



Start PIP for a sequence of commands 
(PIP prompts with "*"). 

*CON: = X.ASM,Y.ASM,Z.ASM <cr> 

Concatenate three ASM files and 
copy to the CON device. 

*X.HEX = CON:,Y.HEX,PTR: <cr> 

Create a HEX file by reading CON 
(until a ctl-Z is typed), followed by 
data from Y.HEX, followed by data 
from PTR until a ctl-Z is encountered. 

*<cr> Single carriage return stops PIP. 
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PIP PUN: = NUL:,X.ASM,EOF:,NUL: <cr> 

Send 40 nulls to the punch device; 
then copy the X.ASM file to the 
punch, followed by an end-of-file 
(ctl-Z) and 40 more null characters. 

The user can also specify one or more PIP parameters, enclosed in 
left and right square brackets, separated by zero or more blanks. 
Each parameter affects the copy operation, and the enclosed list of 
parameters must immediately follow the affected file or device. 
Generally, each parameter can be followed by an optional decimal 
integer value (the S and Q parameters are exceptions). The valid 
PIP parameters are listed below. 

B Block mode transfer: data is buffered by PIP until 

an ASCII x-off character (ctl-S) received from the 
source device. This allows transfer of data to a 
disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, 
PIP clears the disk buffers and returns for more 
input data. The amount of data which can be 
buffered is dependent upon the memory size of 
the host system (PIP will issue an error message 
if the buffers overflow). 

Dn Delete characters which extend past column n in 

the transfer of data to the destination from the 
character source. This parameter is used most 
often to truncate long lines which are sent to a 
(narrow) printer or console device. 

E Echo all transfer operations to the console as 

they are being performed. 

F Filter form feeds from the file. All imbedded 

form feeds are removed. The P parameter can be 
used simultaneously to insert new form feeds. 
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Gn Get file from user number n. (n is the range 

0-15.) Allows one user area to receive data files 
from another. If the operator has issued the 
USER 4 command at the CCP level, the 
PIP statement 

PIPX.Y = X.Y[G2] 

reads file X.Y from user number 2 into user area 
number 4. You cannot copy files into a different 
area than the one which is currently addressed 
by the USER command. 

H Hex data transfer: all data is checked for proper 

Intel hex file format. Non-essential characters 
between hex records are removed during the 
copy operation. The console will be prompted for 
corrective action in case errors occur. 

I Ignore ":00" records in the transfer of Intel 

hex format file (the I parameter automatically 
sets the H parameter). 

L Translate upper case alphabetics to lower case. 

N Add line numbers to each line transferred to 

the destination, starting at one, and incrementing 
by 1. Leading zeroes are suppressed, and the 
number is followed by a colon. If N2 is specified, 
then leading zeroes are included, and a tab is 
inserted following the number. The tab is 
expanded if T is set. 

O Object file (non-ASCII) transfer: the normal 

CP/M end of file is ignored. 

Pn Include page ejects at every n lines (with an 

initial page eject). If n = 1 or is excluded 
altogether, page ejects occur every 60 lines. If 
the F parameter is used, form feed suppression 
takes place before the new page ejects are 
inserted. 

QsTz Quit copying from the source device or file 
when the string s (terminated by ctl-Z) is 
encountered. 
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R Read system files. Allows files with the system 

attribute to be included in PIP transfers. 
Otherwise, system files are not recognized. 

SsTz Start copying from the source device when 

the string s is encountered (terminated by ctl-Z). 
The S and Q parameters can be used to 
"abstract" a particular section of a file (such as 
a subroutine). The start and quit strings are always 
included in the copy operation. 



Note 

The strings following the s and q parameters are translated 
to upper case by the CCP if form (2) of the PIP command 
is used. Form (1 ) of the PIP invocation, however, does not 
perform the automatic upper case translation. 

(1)PIP<cr> 

(2) PIP "command line" <cr> 

Tn Expand tabs (ctl-l characters) to every nth column 

during the transfer of characters to the 
destination from the source. 

U Translate lower case alphabetics to upper case 

during the copy operation. 

V Verify that data has been copied correctly by 

rereading after the write operation (the 
destination must be a disk file). 

W Write over R/O files without console interrogation. 

Under a normal operation, PIP will not 
automatically overwrite a file which is set to 
a permanent R/O status. It advises the user of 
the R/O status and waits for overwrite approval. 
W allows the user to bypass this interrogation 
process. 

Z Zero the parity bit on input for each 

ASCII character. 
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The following are valid PIP commands which specify parameters 
in the file transfer: 



PIPX.ASM = B:[v] 



<cr: 



PIPLST: = X.ASM[nt8u]<cr 



Copy X.ASM from drive B to the 
current drive and verify that the data 
was properly copied. 

Copy X.ASM to the LST: device; 
number each line, expand tabs to 
every eighth column, and translate 
lower case alphabetics to upper case. 
PIP PUN: = X.HEX[i],Y.ZOT[h] <cr > 

First copy X.HEX to the PUN: device 
and ignore the trailing ":00" record 
in X.HEX; then continue the transfer 
of data by reading Y.ZOT, which 
contains hex records, including any 
":00" records which it contains. 

PIPX.LIB = Y.ASM [sSUBR1:TzqJMP L3Tz] <cr> 

Copy from the file Y.ASM into the file 
X.LIB. Start the copy when the string 
"SUBR1 :" has been found, and quit 
copying after the string "JMP L3" is 
encountered. 

PIP LST: = X.ASM[p50] Send X.ASM to the LST: device, with 

line numbers, tabs expanded to every 
eighth column, and page ejects at 
every 50th line. Note that nt8p60 is 
the assumed parameter list for a LST 
file; p50 overrides the default value. 

Note that the PIP program itself is initially copied to a user area (so 
that subsequent files can be copied) using the SAVE command. 
The sequence of operations shown below effectively moves PIP 
from one user area to the next. 
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USERO 
DDT PIP.COM 
(note PIP sizes) 
GO 

USER 3 
SAVEsPIP.com 



login user 

load PIP in memory 

return to CCP 
login user 3 



where s is the integral number of memory "pages" (256 byte 
segments) occupied by PIP. The number s can be determined 
when PIP.COM is located under DDT, by referring to the value 
under the "NEXT" display. If for example, the next available 
address is 1D00, then PIP.COM requires 1C hexadecimal pages 
1 times 16+12 = 28 pages), and thus the value of s is 28 in the 
subsequent save. Once PIP is copied in this manner, it can then be 
copied to another disk belonging to the same user number 
through normal PIP transfers. 



or 



ED 

The ED program is the CP/M system context editor, which allows 
creation and alteration of ASCII files in the CP/M environment. 
Complete details of operation are given in Chapter 3 CP/M ED. In 
general, ED allows the operator to create and operate upon 
source files which are organized as a sequence of ASCII characters, 
separated by end-of-line characters (a carriage-return line-feed 
sequence). There is no practical restriction on line length (no single 
line can exceed the size of the working memory), which is 
instead defined by the number of characters typed between <cr^ s. 
The ED program has a number of commands for character string 
searching, replacement, and insertion, which are useful in the 
creation and correction of programs or text files under CP/M. 
Although the CP/M has a limited memory work space area, 
the file size which can be edited is not limited, since data is easily 
"paged" through this work area. 

Upon initiation, ED creates the specified source file, if it does not 
exist, and opens the file for access. The programmer then 
"appends" data from the source file into the work area, if the 
source file already exists (see the A command), for editing. The 
appended data can then be displayed, altered, and written from the 
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work area back to the disk (see the W command). Particular 
points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular 
portions of a large file. 

Given that the operator has typed 

ED X.ASM <cr> 
the ED program creates an intermediate work file with the name 

X.$$$ 

to hold the edited data during the ED run. Upon completion of ED, 
the X.ASM file (original file) is renamed to X.BAK, and the edited 
work file is renamed to X.ASM. Thus, the X.BAK file contains the 
original (unedited) file, and the X.ASM file contains the newly 
edited file. The operator can always return to the previous version 
of a file by removing the most recent version, and renaming the 
previous version. Suppose, for example, that the current X.ASM 
file was improperly edited; the sequence of CCP commands 
shown below would reclaim the backup file. 



DIRX.* 

ERA X.ASM 

REN X.ASM = X.BAK 



Check to see that BAK file is 
available. 

Erase most recent version. 

Rename the BAK file to ASM. 



Note that the operator can abort the edit at any point (reboot, 
power failure, ctl-C, or Q command) without destroying the original 
file. In this case, the BAK file is not created, and the original file 
is always intact. 

The ED program also allows the user to "ping-pong" the source and 
create backup files between two disks. The form of the ED 
command in this case is 

EDufnd: 

where ufn is the name of a file to edit on the currently logged disk 
and d is the name of an alternate drive. The ED program reads 
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and processes the source file, and writes the new file to drive d, 
using the name ufn. Upon completion of processing, the original 
file becomes the backup file. Thus, if the operator is addressing 
disk A, the following command is valid: 

ED X.ASM B: 

which edits the file X.ASM on drive A, creating the new file 
X.$$$ on drive B. Upon completion of a successful edit, A:X.ASM is 
renamed to A:X.BAK, and B:X.$$$ is renamed to B:X.ASM. For 
user convenience, the currently logged disk becomes drive B at 
the end of the edit. Note that if a file by the name B.X.ASM 
exists before the editing begins, the message 



FILE EXISTS 

is printed at the console as a precaution against accidentally 
destroying a source file. In this case, the operator must first 
ERAse the existing file and then restart the edit operation. 

Similar to other transient commands, editing can take place on a 
drive different from the currently logged disk by preceding the 
source file name by a drive name. Examples of valid edit requests 
are shown below 



EDA:X.ASM 



ED B:X.ASM A: 



Edit the file X.ASM on drive A, 
with new file and backup on 
drive A. 

Edit the file X.ASM on drive B 
to the temporary file X.$$$ on 
drive A. On termination of 
editing, change X.ASM on drive 
B to X.BAK, and change X.$$$ 
on drive A to X.ASM. 



ED takes file attributes into account. If the operator attempts to 
edit a read/only file, the message 



**FILE IS READ/ONLY* 



appears at the console. The file can be loaded and examined, but 
cannot be altered in any way. Normally the operator simply ends 
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the edit session, and uses STAT to change the file attribute to R/W. 
If the edited file has the system attribute set, the message 

"SYSTEM" FILE NOT ACCESSIBLE 

is displayed at the console, and the edit session is aborted. 
Again, the STAT program can be used to change the system 
attribute if desired. 

SUBMIT 

The SUBMIT command allows CP/M commands to be batched 
together for automatic processing. The format of SUBMIT is: 

SUBMIT ufn parm #1 ...parm #n<cr> 

The ufn given in the SUBMIT command must be the filename of 
a file which exists on the currently logged disk, with an assumed 
file type of "SUB." The SUB file contains CP/M prototype 
commands, with possible parameter substitution. The actual 
parameters parm #1 ... parm #n are substituted into the prototype 
commands, and, if no errors occur, the file of substituted 
commands is processed sequentially by CP/M. 

The prototype command file is created using the ED program, with 
interspersed "$" parameters of the form 



51 $2 $3 



$n 



corresponding to the number of actual parameters which will be 
included when the file is submitted for execution. When the SUBMIT 
transient is executed, the actual parameters parm #1 ... parm #n 
are paired with the formal parameters $1 ...$n in the prototype 
commands. If the number of formal and actual parameters does 
not correspond, then the submit function is aborted with an error 
message at the console. The SUBMIT function creates a file of 
substituted commands with the name 

$$$.SUB 



on the logged disk. When the system reboots (at the termination of 
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the SUBMIT) this command file is read by the CCP as a source 
of input rather than the console. If the SUBMIT function is 
performed on any disk other than drive A, the commands are not 
processed until the disk is inserted into drive A and the system 
reboots Further the user can abort command processing at any 
time by typing a rubout when the command is read and echoed. In 
this case the $$$ SUB file is removed, and the subsequent 
commands come from the console. Command processing is also 
aborted if the CCP detects an error in any of the commands. 
Programs which execute under CP/M can abort processing of 
command files when error conditions occur by simply erasing 
any existing $$$. SUB file. 

In order to introduce dollar signs into a SUBMIT file, the user may 
type a "$$" which reduces to a single "$" within the command 
file Further an up-arrow symbol "T" may precede an alphabetic 
character x, which produces a single ctl-x character within the 
file. 

The last command in a SUB file can initiate another SUB file, thus 
allowing chained batch commands. 

Suppose the file ASMBL.SUB exists on disk and contains the 
prototype commands 

ASM $1 
DIR $1.* 
ERA*.BAK 
PIP$2 = $1.PRN 
ERA$1.PRN 



and the command 

SUBMIT ASMBLXPRN<cr> 

is issued by the operator. The SUBMIT program reads the 
ASMBL SUB file substituting "X" for all occurrences of $1 and 
"PRN" for all occurrences of $2, resulting in a $$$.SUB file 
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containing the commands 

ASMX 

DIRX* 

ERA*.BAK 

PIPPRN: = X.PRN 

ERAX.PRN 

which are executed in sequence by the CCR 

The SUBMIT function can access a SUB file which is on an alternate 
drive by preceding the file name by a drive name. Submitted 
files are only acted upon, however, when they appear on drive A. 
Thus, it is possible to create a submitted file on drive B which is 
executed at a later time when it is inserted in drive A. 

XSUB 

XSUB extends the power of the SUBMIT facility to include character 
input during program execution as well as entering command 
lines. The XSUB command is included as the first line of your 
submit file and, when executed, self-relocates directly below the 
CCP 

All subsequent submit command lines are processed by XSUB, so 
that programs which read buffered console input (BDOS function 
10) receive their input directly from the submit file. For example, 
the file SAVER. SUB could contain the submit lines: 

XSUB 

DDT 

l$1.HEX 

R 

GO 

SAVE 1 $2.COM 

with a subsequent SUBMIT command: 

SUBMIT SAVER XY 

which substitutes X for $1 and Y for $2 in the command stream. 
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The XSUB program loads, followed by DDT which is sent the 
command lines "IX.HEX" "R" and "GO," thus returning to the CCP. 
The final command "SAVE 1 YCOM" is processed by the CCP. 

The XSUB program remains in memory, and prints the message 

(xsub active) 

on each warm start operation to indicate its presence. Subsequent 
submit command streams do not require the XSUB, unless an 
intervening cold start has occurred. Note that XSUB must be 
loaded after DESPOOL, if both are to run simultaneously. 

DUMP 

The DUMP program types the contents of the disk file (ufn) at the 
console in hexadecimal form. The file contents are listed sixteen 
bytes at a time, with the absolute byte address listed to the left of 
each line in hexadecimal. Long typeouts can be aborted by 
pushing the rubout key during printout. (The source listing of the 
DUMP program is given in the "CP/M Interface Guide" as an 
example of a program written for the CP/M environment.) 



BDOS Error Messages 



There are three error situations which the Basic Disk Operating 
System intercepts during file processing. When one of these 
conditions is detected, the BDOS prints the message: 

BDOS ERR ON x: error 

where x is the drive name, and "error" is one of the three error 
messages: 



BAD SECTOR 

SELECT 

R/O 

The "BAD SECTOR" message indicates that the disk controller 
electronics has detected an error condition in reading or writing 
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the diskette. This condition is generally due to a malfunctioning 
disk controller, or an extremely worn diskette. If you find that 
your system reports this error more than once a month, you should 
check the state of your controller electronics, and the condition 
of your media. In any case, recovery from this condition is 
accomplished by typing a ctl-C to reboot (this is the safest!), or a 
return, which simply ignores the bad sector in the file operation. 
Note, however, that typing a return may destroy your diskette 
integrity if the operation is a directory write, so make sure you 
have adequate backups in this case. 

The "SELECT" error occurs when there is an attempt to address a 
drive beyond the A through D range. In this case, the value of x in 
the error message gives the selected drive. The system reboots 
following any input from the console. 

The R/O (read only) message occurs when there is an attempt to 
write to a diskette which has been designated as read-only in a 
STAT command, or has been set to read-only by the BDOS. In 
general, the operator should reboot CP/M either by using the 
warm start procedure ctl-C or by performing a cold start whenever 
the diskettes are changed. If a changed diskette is to be read but 
not written, BDOS allows the diskette to be changed without the 
warm or cold start, but internally marks the drive as read-only. 
The status of the drive is subsequently changed to read/write for 
input from the console. An automatic warm start takes place 
following any input. 
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Introduction 



This manual describes CP/M, release 2, system organization 
including the structure of memory and system entry points. The 
intention is to provide the necessary information required to write 
programs which operate under CP/M, and which use the peripheral 
and disk I/O facilities of the system. 

CP/M is logically divided into four parts, called the Basic I/O 
System (BIOS), the Basic Disk Operating System (BDOS), the 
Console command processor (CCP), and the Transient Program 
Area (TPA). The BIOS is a hardware-dependent module which 
defines the exact low level interface to a particular computer 
system which is necessary for peripheral device I/O. The BIOS and 
BDOS are logically combined into a single module with a common 
entry point, and referred to as the FDOS. The CCP is a distinct 
program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the backup 
storage device. The TPA is an area of memory (i.e., the portion 
which is not used by the FDOS and CCP) where various non- 
resistant operating system commands and user programs are 
executed. The lower portion of memory is reserved for system 
information and is detailed in later sections. 
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Memory organization of the CP/M system is shown below: 



high memory 
FBASE: 
CBASE: 

TBASE: 
BOOT: 



FDOS (BDOS + BIOS) 



CCP 



TPA 



system parameters 



Base addresses for the two Apple memory configurations that 
can be used with CP/M are shown in the table below: 



Module 



44 K 



56K (Language Card) 



CCP 


9400 H 


C400H 


BDOS 


9C00H 


CC00H 


BIOS 


AA00H 


DA00H 


Top of RAM 


AFFFH 


DFFFH 



All standard CP/M versions assume BOOT=0000H, which is the 
base of random access memory. The machine code found at 
location BOOT performs a system "warm start" which loads and 
initializes the programs and variables necessary to return control 
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to the CCP. Thus, transient programs need only jump to location 
BOOT to return control to CP/M at the command level. Further, 
the standard versions assume TBASE=BOOT+01 00H which is 
normally location 0100H. The principal entry point to the FDOS 
is at location BOOT+0005H (normally 0005H) where a jump to 
FBASE is found. The address field at BOOT+0006H (normally 
0006H) contains the value of FBASE and can be used to determine 
the size of available memory, assuming the CCP is being 
overlayed by a transient program. 

Transient programs are loaded into the TPA and executed as 
follows. The operator communicates with the CCP by typing 
command lines following each prompt. Each command line takes 
one of the forms: 

command 
command filel 
command filel file2 

where "command" is either a built-in function such as DIR or 
TYPE, or the name of a transient command or program. If the 
command is a built-in function of CP/M, it is executed immediately. 
Otherwise, the CCP searches the currently addressed disk for a 
file by the name 

command.COM 



If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at TBASE in memory. The CCP loads the COM file from the disk 
into memory starting at TBASE and possibly extending up to 
CBASE. 

If the command is followed by one or two file specifications, the 
CCP prepares one or two file control block (FCB) names in the 
system parameter area. These optional FCB's are in the form 
necessary to access files through the FDOS, and are described 
in the next section. 
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The transient program receives control from the CCP and begins 
execution, perhaps using the I/O facilities of the FDOS. The 
transient program is "called" from the CCP, and thus can simply 
return to the CCP upon completion of its processing, or can jump 
to BOOT to pass control back to CP/M. In the first case, the 
transient program must not use memory above CBASE, while in 
the latter case, memory up through FBASE-1 is free. 

The transient program may use the CP/M I/O facilities to 
communicate with the operator's console and peripheral devices, 
including the disk subsystem. The I/O system is accessed by 
passing a "function number" and an "information address" to CP/M 
through the FDOS entry point at BOOT+005H. In the case of a 
disk read, for example, the transient program sends the number 
corresponding to a disk read, along with the address of an FCB 
to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error 
number indicating that the disk read was unsuccessful. The function 
numbers and error indicators are given below. 
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Operating System Call Conventions 



The purpose of this section is to provide detailed information for 
performing direct operating system calls from user programs. 

CP/M facilities which are available for access by transient 
programs fall into two general categories: simple device I/O, and 
disk file I/O. The simple device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 

The FDOS operations which perform disk Input/Output are 

Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Available Disks 

Interrogate Selected Disk 

Set DMA Address 

Set/Reset File Indicators 

As mentioned above, access to the FDOS functions is accomplished 
by passing a function number and information address through 
the primary entry point at location BOOT+0005H. In general, the 
function number is passed in register C with the information 
address in the double byte pair DE. Single byte values are returned 
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in register A, with double byte values returned in HL (a zero 
value is returned when the function number is out of range). For 
reasons of compatibility, register A=L and register B=H upon 
return in all cases. The CP/M function numbers are: 



System Reset 


19 Delete File 


1 Console Input 


20 Read Sequential 


2 Console Output 


21 Write Sequential 


3 Reader Input 


22 Make File 


4 Punch Output 


23 Rename File 


5 List Output 


24 Return Login Vector 


6 Direct Console I/O 


25 Return Current Disk 


7 Get I/O Byte 


26 Set DMA Address 


8 Set I/O Byte 


27 Get Addr (Alloc) 


9 Print String 


28 Write Protect Disk 


10 Read Console Buffer 


29 Get R/O Vector 


1 1 Get Console Status 


30 Set File Attributes 


12 Return Version Number 


31 Get Addr (Disk Parms 


13 Reset Disk System 


32 Set/Get User Code 


14 Select Disk 


33 Read Random 


15 Open File 


34 Write Random 


16 Close File 


35 Compute File Size 


17 Search for First 


36 Set Random Record 


18 Search for Next 





(Functions 28 and 32 should be avoided in application programs to 
maintain upward compatibility with MP/M.) 

Upon entry to a transient program, the CCP leaves the stack 
pointer set to an eight level stack area with the CCP return address 
pushed onto the stack, leaving seven levels before overflow 
occurs. Although this stack is usually not used by a transient 
program (i.e., most transients return to the CCP through a jump 
to location 0000H), it is sufficiently large to make CP/M system 
calls since the FDOS switches to a local stack at system entry. 
The following assembly language program segment, for example, 
reads characters continuously until an asterisk is encountered, at 
which time control returns to the CCP (assuming a standard CP/M 
system with BOOT+0000H): 
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BDOS 


EQU 


0005 H 


CONIN 


EQU 


1 


' 


ORG 


0100H 


NEXTC: 


MVI 


C.CONIN 




CALL 


BDOS 




CPI 


'*' 




JNZ 


NEXTC 




RET 






END 





;STANDARD CP/M ENTRY 
;CONSOLE INPUT FUNCTION 

BASE OF TPA 

READ NEXT CHARACTER 

RETURN CHARACTER IN <A> 

END OF PROCESSING? 

LOOP IF NOT 

RETURN TO CCP 



CP/M implements a named file structure on each disk, providing a 
logical organization which allows any particular file to contain 
any number of records from completely empty to the full capacity 
of the drive. Each drive is logically distinct with a disk directory 
and file data area. The disk file names are in three parts: the drive 
select code, the file name consisting of one to eight non-blank 
characters, and the file type consisting of zero to three non-blank 
characters. The file type names the generic category or a 
particular file, while the file name distinguishes individual files in 
each category. The file types listed below name a few generic 
categories which have been established, although they are generally 
arbitrary: 



ASM Assembler Source PLI 

PRN Printer Listing REL 

HEX Hex Machine Code TEX 

BAS Basic Source File BAK 

INT Intermediate Code SYM 



PL/I Source File 
Relocatable Module 
TEX Formatter Source 
ED Source Backup 
SID Symbol File 



COM CCP Command File $$$ Temporary File 

Source files are treated as a sequence of ASCII characters, where 
each "line" of the source file is followed by a carriage-return 
line-feed sequence (ODH followed by OAH). Thus one 128 byte 
CP/M record could contain several lines of source text. The end 
of an ASCII file is denoted by a control-Z character (1 AH) or a real 
end of file, returned by the CP/M read operation. Control-Z 
characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by 
CP/M is used to terminate read operations. 
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Files in CP/M can be thought of as a sequence of up to 65536 
records of 128 bytes each, numbered from through 65535, 
thus allowing a maximum of 8 megabytes per file. Note, however, 
that although the records may be considered logically contiguous, 
they may not be physically contiguous in the disk data area. 
Internally, all files are broken into 16K byte segments called 
logical extents, so that counters are easily maintained as 8-bit 
values. Although the decomposition into extents is discussed in 
the paragraphs which follow, they are of no particular consequence 
to the programmer since each extent is automatically accessed 
in both sequential and random access modes. 

In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). Transient programs often 
use the default file control block area reserved by CP/M at location 
BOOT+005CH (normally 005CH) for simple file operations. The 
basic unit of file information is a 128 byte record used for all file 
operations, thus a default location for disk I/O is provided by 
CP/M at location BOOT+0080H (normally 0080H) which is the 
initial default DMA address (see function 26). All directory 
operations take place in a reserved area which does not affect 
write buffers as was the case in release 1 , with the exception of 
Search for First and Search for Next, where compatibility 
is required. 

The File Control Block (FCB) data area consists of a sequence of 
33 bytes for sequential access and a series of 36 bytes in the 
case that the file is accessed randomly. The default file control 
block normally located at 005CH can be used for random access 
files, since the three bytes starting at BOOT+007DH are available 
for this purpose. The FCB format is shown with the following fields: 



dr 


f1 


f2 


/ / 


f8 


t1 


t2 


t3 


ex 


s1 


s2 


re 


dO 


/ / 


dn 


cr 


rO 


r1 


r2 



00 01 02 



08 09 10 11 12 13 14 15 M 



31 32 33 34 35 
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where 



dr 



f 1 . . . f8 
t1,t2,t3 



ex 

s1 
s2 

re 

dO . . . dn 
cr 

rO, M, r2 



drive code (0-16) 
0=>use default drive for file 
1=>auto disk select drive A, 
2=>auto disk select drive B, 

1 6=>auto disk select drive P. 

contain the file name in ASCII upper case, 
with high bit=o 

contain the file type in ASCII upper case, 

with high bit=0 

t1 ',t2', and t3' denote the bit of these 

positions, 

tr=1=>Read/0nlyfile, 

t2'=1=>SYSfile,noDIR list 

contains the current extent number, 
normally set to 00 by the user, but in range 
0-31 during file I/O 

reserved for internal system use 

reserved for internal system use, set to zero 
on call to OPEN, MAKE, SEARCH 

record count for extent "ex," takes on values 
from - 1 28 

filled-in by CP/M, reserved for system use 

current record to read or write in a 
sequential file operation, normally set to 
zero by user 

optional random record number in the range 
0-65535, with overflow to r2, rO, r1 constitute 
a 16-bit value with low byte rO, and high 
byte r 1 
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Each file being accessed through CP/M must have a corresponding 
FCB which provides the name and allocation information for all 
subsequent file operations. When accessing files, it is the 
programmer's responsibility to fill the lower sixteen bytes of the 
FCB and initialize the "cr" field. Normally, bytes 1 through 1 1 are 
set to the ASCII character values for the file name and file type, 
while all other fields are zero. 

FCB's are stored in a directory area of the disk, and are brought 
into central memory before proceeding with file operations (see 
the OPEN and MAKE functions). The memory copy of the FCB is 
updated as file operations take place and later recorded permanently 
on disk at the termination of the file operation (see the CLOSE 
command). 

The CCP constructs the first sixteen bytes of two optional FCB's for 
a transient by scanning the remainder of the line following the 
transient name, denoted by "filel " and "file2" in the prototype 
command line described above, with unspecified fields set to 
ASCII blanks. The first FCB is constructed at location BOOT+005CH, 
and can be used as-is for subsequent file operations. The second 
FCB occupies the d) . . . dn portion of the first FCB, and must be 
moved to another area of memory before use. If, for example, 
the operator types 

PROGNAME B:X.ZOT Y.ZAP 



the file PROGNAME. COM is loaded into the TPA, and the default 
FCB at BOOT+005CH is initialized to drive code 2, file name "X" 
and file type "ZOT." The second drive code takes the default value 
0, which is placed at BOOT+006CH, with the file name "Y" 
placed into location BOOT+006DH and file type "ZAP" located 8 
bytes later at BOOT+0075H. All remaining fields through "cr" 
are set to zero. Note again that it is the programmer's responsibility 
to move this second file name and type to another area, usually a 
separate file control block, before opening the file which begins at 
BOOT+005CH, due to the fact that the open operation will 
overwrite the second name and type. 

If no file names are specified in the original command, then the 
fields beginning at BOOT+005DH and BOOT+006DH contain 
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blanks. In all cases, the CCP translates lower case alphabetics to 
upper case to be consistent with the CP/M file naming 
conventions. 

As an added convenience, the default buffer area at location 
BOOT+0080H is initialized to the command line tail typed by the 
operator following the program name. The first position contains 
the number of characters, with the characters themselves following 
the character count. Given the above command line, the area 
beginning at BOOT+0080H is initialized as follows: 



BOOT+0080H: 










+00+01 +02+03+04+05+06+07+08+09+10+11 +12+13+14 


14 B" ":" 


"X" " 


." "Z" "0" 


"T Y" " 


." "Z" "A" "P" 



where the characters are translated to upper case ASCII with 
uninitialized memory following the last valid character. Again, it 
is the responsibility of the programmer to extract the information 
from this buffer before any file operations are performed, unless 
the default DMA address is explicitly changed. 

The individual functions are described in detail in the pages which 
follow. 

Function 0: System Reset 



Entry Parameters: 
Register 



C: 00H 



The system reset function returns control to the CP/M operating 
system at the CCP level. The CCP re-initializes the disk subsystem 
by selecting and logging-in disk drive A. This function has exactly 
the same effect as a jump to location BOOT. 
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Function 1: Console Input 



Entry Parameters: 
Register 

Returned Value: 
Register 



C: 01 H 



A: ASCII Character 



The console input function reads the next console character to 
register A. Graphic characters, along with carriage return, line 
feed, and backspace (ctl-H) are echoed to the console. Tab 
characters (ctl-l) are expanded in columns of eight characters. A 
check is made for start/stop scroll (ctl-S) and start/stop printer 
echo (ctl-P). The FDOS does not return to the calling program 
until a character has been typed, thus suspending execution of a 
character if not ready. 

Function 2: Console Output 



Entry Parameters: 

Register 
Register 



C: 02H 

E: ASCII Character 



The ASCII character from register E is sent to the console 
device. Similar to function 1 , tabs are expanded and checks are 
made for start/stop scroll and printer echo. 

Function 3: Reader Input 



Entry Parameters: 
Register 

Returned Value: 
Register 



C: 03H 



A: ASCII Character 



The Reader Input function reads the next character from the 
logical reader into register A. Control does not return until the 
character has been read. 
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Function 4: Punch Output 



Entry Parameters: 

Register 
Register 



C: 04H 

E: ASCII Character 



The Punch Output function sends the character from register E to 
the logical punch device. 

Function 5: List Output 



Entry Parameters: 

Register 
Register 



C: 05H 

E: ASCII Character 



The List Output function sends the ASCII character in register E to 
the logical listing device. 

Function 6: Direct Console I/O 



Entry Parameters: 

Register 
Register 



C: 06 H 

E: OFFH (input) or 
char (output) 



Returned Value: 
Register 



char or status 
(no value) 



Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is 
required. Use of this function should, in general, be avoided since 
it bypasses all of CP/M's normal control character functions (e.g., 
control-S and control-P). Programs which perform direct I/O through 
the BIOS under previous releases of CP/M, however, should be 
changed to use direct I/O under BDOS so that they can be fully 
supported under future releases of MP/M and CP/M. 
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Upon entry to function 6, register E either contains hexadecimal 
FF, denoting a console input request, or register E contains an 
ASCII character. If the input value is FF, then function 6 returns 
A=00 if no character is ready, otherwise A contains the next 
console input character. 

If the input value in E is not FF, then function 6 assumes that E 
contains a valid ASCII character which is sent to the console. 



Function 7: Get I/O Byte 

Entry Parameters: 

Register C: 07H 



Returned Value: 
Register 



A: I/O Byte Value 



The Get I/O Byte function returns the current value of IOBYTE in 
register A. 

Function 8: Set I/O Byte 



Entry Parameters: 

Register 
Register 



C: 08H 

E: I/O Byte Value 



The Set I/O Byte function changes the system IOBYTE value to 
that given in register E. 



Function 9: Print String 

Entry Parameters: 

Register C: 09H 

Registers DE: String Address 

The Print String function sends the character string stored in 
memory at the location given by DE to the console device, until a 
"$" is encountered in the string. Tabs are expanded as in function 
2, and checks are made for start/stop scroll and printer echo. 
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Function 10: Read Console Buffer 



Entry Parameters: 

Register 
Registers 



C: OAH 
DE: Buffer Address 



Returned Value: 

Console Characters in Buffer 

The Read Buffer function reads a line of edited console input 
into a buffer addressed by registers DE. Console input is terminated 
when either the input buffer overflows. The Read Buffer takes 
the form: 



DE: +0 +1 +2 +3 +4 +5 +6 +7 +t 



+ n 



mx 


nc 


d 


c2 


c3 


c4 


c5 


c6 


C7 




?? 



where "mx" is the maximum number of characters which the buffer 
will hold (1 to 255), "nc" is the number of characters read (set by 
FDOS upon return), followed by the characters read from the 
console. If nc < mx, then uninitialized positions follow the last 
character, denoted by "??" in the above figure. A number of control 
functions are recognized during line editing: 

rub/del removes and echoes the last character 

ctl-C reboots when at the beginning of line 

ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 

ctl-X backspaces to beginning of current line 

Note also that certain functions which return the carriage to the 
leftmost position (e.g., ctl-X) do so only to the column position 
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where the prompt ended (in earlier releases, the carriage returned 
to the extreme left margin). This convention makes operator data 
input and line correction more legible. 

Function 1 1: Get Console Status 



Entry Parameters: 
Register 

Return Value: 

Register 



C: OBH 



A: Console Status 



The Console Status function checks to see if a character has been 
typed at the console. If a character is ready, the value OFFH is 
returned in register A. Otherwise a 00H value is returned. 

Function 12: Return Version Number 



Entry Parameters: 
Register 

Returned Value: 
Registers 



C: OCH 



HL: Version Number 



Function 12 provides information which allows version independent 
programming. A two-byte value is returned, with FNOO designating 
the CP/M release (H=01 for MP/M), and L=00 for all releases 
previous to 2.0. CP/M 2.0 returns a hexadecimal 20 in register L, 
with subsequent version 2 releases in the hexadecimal range 21 , 
22, through 2F Using function 12, for example, you can write 
application programs which provide both sequential and random 
access functions, with random access disabled when operating 
under early releases of CP/M. 



CP/M Reference Manual 



Function 13: Reset Disk System 



Entry Parameters: 
Register 



C: ODH 



The Reset Disk function is used to programmatically restore the 
file system to a reset state where all disks are set to read/write 
(see functions 28 and 29), only disk drive A is selected, and the 
default DMA address is reset to BOOT+0080H. This function can 
be used, for example, by an application program which requires a 
disk change without a system reboot. 



Function 14: Select Disk 



Entry Parameters: 

Register 
Register 



C: OEH 

E: Selected Disk 



The Select Disk function designates the disk drive named in 
register E as the default disk for subsequent file operations, with 
E=0 for drive A, 1 for drive B, and so-forth through 15 corresponding 
to drive P in a full sixteen drive system. The drive is placed in an 
"on-line" status which, in particular, activates its directory until the 
next cold start, warm start, or disk system reset operation. If the 
disk media is changed while it is on-line, the drive automatically 
goes to a read/only status in a standard CP/M environment (see 
function 28). FCB's which specify drive code zero (dr=OOH) 
automatically reference the currently selected default drive. 
Drive code values between 1 and 16, however, ignore the selected 
default drive and directly reference drives A through P. 
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Function 15: Open File 



Entry Parameters: 

Register 
Registers 

Returned Value: 
Register 



C: OFH 
DE: FCB Address 



A: Directory Code 



The Open File operation is used to activate a file which currently 
exists in the disk directory for the currently active user number. 
The FDOS scans the referenced disk directory for a match in 
positions 1 through 14 of the FCB referenced by DE (byte s1 is 
automatically zeroed), where an ASCII question mark (3FH) 
matches any directory character in any of these positions. 
Normally, no question marks are included and, further, bytes "ex" 
and "s2" of the FCB are zero. 

If a directory element is matched, the relevant directory information 
is copied into bytes dO through dn of the FCB, thus allowing 
access to the files through subsequent read and write operations. 
Note that an existing file must not be accessed until a successful 
open operation is completed. Upon return, the open function 
returns a "directory code" with the value through 3 if the open 
was successful, or OFFH (255 decimal) if the file cannot be found. 
If question marks occur in the FCB then the first matching FCB 
is activated. Note that the current record ("cr") must be zeroed by 
the program if the file is to be accessed sequentially from the 
first record. 
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Function 16: Close File 



Entry Parameters: 

Register 
Registers 

Returned Value: 
Register 



C: 
DE: 



10H 

FCB Address 



A: Directory Code 



The Close File function performs the inverse of the open file 
function. Given that the FCB addressed by DE has been previously 
activated through an open or make function (see functions 15 
and 22), the close function permanently records the new FCB in 
the referenced disk directory. The FCB matching process for the 
close is identical to the open function. The directory code returned 
for a successful close operation is 0, 1 , 2, or 3, while a OFFH 
(255 decimal) is returned if the file name cannot be found in the 
directory. A file need not be closed if only read operations have 
taken place. If write operations have occurred, however, the close 
operation is necessary to permanently record the new directory 
information. 

Function 17: Search for First 



Entry Parameters: 

Register 
Registers 

Returned Value: 
Register 



C: 
DE: 



11H 

FCB Address 



A: Directory Code 



Search for First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise 0, 1 , 2, or 3 is returned 
indicating the file is present. In the case that the file is found, the 
current DMA address is filled with the record containing the 
directory entry, and the relative starting position is A *32 (i.e., 
rotate the A register left 5 bits, or ADD A five times). Although 
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not normally required for application programs, the directory 
information can be extracted from the buffer at this position. 

An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from "f1 " through "ex" matches the corresponding field of 
any directory entry on the default or auto-selected disk drive. If 
the "dr" field contains an ASCII question mark, then the auto disk 
selected function is disabled, the default disk is searched, with 
the search function returning any matched entry, allocated or free, 
belonging to any user number. This latter function is not normally 
used by application programs, but does allow complete flexibility to 
scan all current directory values. If the "dr" field is not a question 
mark, the "s2" byte is automatically zeroed. 



Function 18: Search for Next 



Entry Parameters: 
Register 



C: 12H 



Returned Value: 
Register 



A: Directory Code 



The Search for Next function is similar to the Search for First 
function, except that the directory scan continues from the last 
matched entry. Similar to function 17, function 18 returns the decimal 
value 255 in A when no more directory items match. 

Function 19: Delete File 



Entry Parameters: 

Register C: 

Registers DE: 



13H 

FCB Address 



Returned Value: 
Register 



A: Directory Code 



The Delete File function removes files which match the FCB 
addresses by DE. The filename and type may contain ambiguous 
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references (i.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search for 
Next functions. 

Function 1 9 returns a decimal 255 if the referenced file or files 
cannot be found, otherwise a value in the range to 3 is 
returned. 



Function 20: Read Sequential 

Entry Parameters: 



Register 
Registers 

Returned Value: 
Register 



C: 
DE: 



14H 

FCB Address 



A: Directory Code 



Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Read Sequential 
function reads the next 128 byte record from the file into memory 
at the current DMA address. The record is read from position "cr" 
of the extent, and the "cr" field is automatically incremented to 
the next record position. If the "cr" field overflows then the next 
logical extent is automatically opened and the "cr" field is reset 
to zero in preparation for the next read operation. The value 00H is 
returned in the A register if the read operation was successful, 
while a non-zero value is returned if no data exists at the next 
record position (e.g., end of file occurs). 

Function 21: Write Sequential 



Entry Parameters: 

Register 
Registers 

Returned Value: 
Register 



C: 15H 
DE: FCB Address 



A: Directory Code 
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Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Write 
Sequential function writes the 128 byte data record at the current 
DMA address to the file named by the FCB. The record is placed 
at position "cr" of the file, and the "cr" field is automatically 
incremented to the next record position. If the "cr" field overflows 
then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next write operation. 
Write operations can take place into an existing file, in which case 
newly written records overlay those which already exist in the 
file. Register A=00H upon return from a successful write operation, 
while a non-zero value indicates an unsuccessful write due to a 
full disk. 



Function 22: Make File 



Entry Parameters: 

Register C: 

Registers DE: 



16H 

FCB Address 



Returned Value: 
Register 



A: Directory Code 



The Make File operation is similar to the open file operation 
except that the FCB must name a file which does not exist in the 
currently referenced disk directory (i.e., the one named explicitly 
by a non-zero "dr" code, or the default disk if "dr" is zero). The 
FDOS creates the file and initializes both the directory and main 
memory value to an empty file. The programmer must ensure that 
no duplicate file names occur, and a preceding delete operation 
is sufficient if there is any possibility of duplication. Upon return, 
register A=0, 1 , 2, or 3 if the operation was successful and OFFH 
(255 decimal) if no more directory space is available. The make 
function has the side-effect of activating the FCB and thus a 
subsequent open is not necessary. 
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Function 23: Rename File 



Entry Parameters: 

Register 
Registers 

Returned Value: 
Register 



C: 
DE: 



17H 

FCB Address 



A: Directory Code 



The Rename function uses the FCB addressed by DE to change 
all occurrences of the file named in the first 16 bytes to the file 
named in the second 16 bytes. The drive code "dr" at position 
is used to select the drive, while the drive code for the new file 
name at position 16 of the FCB is assumed to be zero. Upon 
return, register A is set to a value between and 3 if the rename 
was successful, and OFFH (255 decimal) if the first file name 
could not be found in the directory scan. 

Function 24: Return Login Vector 



Entry Parameters: 
Register 

Returned Value: 
Registers 



C: 18H 



HL: Login Vector 



The login vector value returned by CP/M is a 16-bit value in HL, 
where the least significant bit of L corresponds to the first drive 
A, and the high order bit of H corresponds to the sixteenth drive, 
labelled PA "0" bit indicates that the drive is not on-line, while a 
"1 " bit marks a drive that is actively on-line due to an explicit disk 
drive selection, or an implicit drive select caused by a file 
operation which specified a non-zero "dr" field. Note that 
compatibility is maintained with earlier releases, since registers A 
and L contain the same values upon return. 
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Function 25: Return Current Disk 



Entry Parameters: 
Register 

Returned Value: 
Register 



C: 19H 



A: Current Disk 



Function 25 returns the currently selected default disk number 
in register A. The disk numbers range from through 1 5 
corresponding to drives A through P. 

Function 26: Set DMA Address 



Entry Parameters: 

Regular C: 

Registers DE 



1AH 

DMA Address 



"DMA" is an acronym for Direct Memory Address, which is often 
used in connection with disk controllers which directly access the 
memory of the mainframe computer to transfer data to and from 
the disk subsystem. Although many computer systems use non-DMA 
access (i.e., the data is transferred through programmed I/O 
operations), the DMA address has, in CP/M, come to mean the 
address at which the 128 byte data record resides before a disk 
write and after a disk read. Upon cold start, warm start, or disk 
system reset, the DMA address is automatically set to 
BOOT+0080H. The Set DMA function, however, can be used to 
change this default value to address another area of memory where 
the data records reside. Thus, the DMA address becomes the 
value specified by DE until it is changed by a subsequent Set DMA 
function, cold start, warm start, or disk system reset. 
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Function 27: Get ADDR (ALLOC) 



Entry Parameters: 
Register 

Returned Value: 
Registers 



C: 1BH 



HL: ALLOC Address 



An "allocation vector" is maintained in main memory for each 
on-line disk drive. Various system programs use the information 
provided by the allocation vector to determine the amount of 
remaining storage (see the STAT program). Function 27 returns the 
base address of the allocation vector for the currently selected 
disk drive. The allocation information may, however, be invalid if 
the selected disk has been marked read/only. Although this 
function is not normally used by application programs, additional 
details of the allocation vector are found in the "CP/M Alteration 
Guide." 

Function 28: Write Protect Disk 



Entry Parameters: 
Register 



C: 1CH 



The disk write protect function provides temporary write protection 
for the currently selected disk. Any attempt to write to the disk, 
before the next cold or warm start operation produces the message 

BdosErrond: R/O 
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Function 29: Get Read/Only Vector 



Entry Parameters: 
Register 

Returned Value: 
Registers 



C: 1DH 



HL: R/O Vector Value 



Function 29 returns a bit vector in register pair HL which indicates 
drives which have the temporary read/only bit set. Similar to 
function 24, the least significant bit corresponds to drive A, while 
the most significant bit corresponds to drive P. The R/O bit is set 
either by the explicit call to function 28, or by the automatic 
software mechanisms within CP/M which detect changed disks. 

Function 30: Set File Attributes 



Entry Parameters: 

Register 
Registers 



Returned Value: 
Register 



C: 
DE: 



1EH 

FCB Address 



A: Directory Code 



The Set File Attributes function allows programmatic manipulation 
of permanent indicators attached to files. In particular, the R/O 
and System attributes (t1 ' and t2') can be set or reset. The DE pair 
addresses an unambiguous file name with the appropriate 
attributes set or reset. Function 30 searches for a match, and 
changes the matched directory entry to contain the selected 
indicators. Indicators f 1 ' through f4' are not presently used, but 
may be useful for applications programs, since they are not 
involved in the matching process during file open and close 
operations. Indicators f5' through f8' and t3' are reserved for 
future system expansion. 
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Function 3 1: Get ADDR (Disk PARMS) 



Entry Parameters: 
Register 

Returned Value: 
Registers 



C: 1FH 



HL: DPB Address 



The address of the BIOS resident disk parameter block is returned 
in HL as a result of this function call. This address can be used 
for either of two purposes. First, the disk parameter values can be 
extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk 
parameters when the disk environment changes, if required. 
Normally, application programs will not require this facility. 

Function 32: Set/Get User Code 



Entry Parameters: 

Register 
Register 



Returned Value: 
Register 



C: 20H 

E: 0FFH(get)or 
User Code (set) 



A: Current Code or 
(no value) 



An application program can change or interrogate the currently 
active user number by calling function 32. If register E=0FFH, then 
the value of the current user number is returned in register A, 
where the value is in the range to 31 . If register E is not OFFH, 
then the current user number is changed to the value of E 
(modulo 32). 



CP/M 2.0 Interface Guide 



Function 33: Read Random 

Entry Parameters: 



Register 
Registers 


C: 
DE: 


21H 

FCB Address 


Returned Value: 






Register 


A: 


Return Code 



The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation 
takes place at a particular record number, selected by the 24-bit 
value constructed from the three byte field following the FCB (byte 
positions rO at 33, r1 at 34, and r2 at 35). Note that the sequence 
of 24 bits is stored with least significant byte first (rO), middle byte 
next (r1 ), and high byte last (r2). CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 must 
be zero, however, since a non-zero value indicates overflow past 
the end of file. 

Thus, the r0,r1 byte pair is treated as a double-byte, or "word" 
value, which contains the record to read. This value ranges from 
to 65535, providing access to any particular record of the 8 
megabyte file. In order to process a file using random access, 
the base extent (extent 0) must first be opened. Although the base 
extent may or may not contain any allocated data, this ensures 
that the file is properly recorded in the directory, and is visible in 
DIR requests. The selected record number is then stored into 
the random record field (r0,r1 ), and the BDOS is called to read the 
record. Upon return from the call, register A either contains an 
error code, as listed below, or the value 00 indicating the operation 
was successful. In the latter case, the current DMA address 
contains the randomly accessed record. Note that contrary to the 
sequential read operation, the record number is not advanced. 
Thus, subsequent random read operations continue to read the 
same record. 
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Upon each random read operation, the logical extent and current 
record values are automatically set. Thus, the file can be sequentially 
read or written, starting from the current randomly accessed 
position. Note, however, that in this case, the last randomly read 
record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation. You can, of course, simply 
advance the random record position following each random read or 
write to obtain the effect of a sequential I/O operation. 

Error codes returned in Register A following a random read are 
listed below. 

01 reading unwritten data 

02 (not returning in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 



Error code 01 and 04 occur when a random read operation accesses 
a data block which has not been previously written, or an extent 
which has not been created, which are equivalent conditions. Error 
3 does not normally occur under proper system operation, but 
can be cleared by simply re-reading, or re-opening extent zero as 
long as the disk is not physically write protected. Error code 06 
occurs whenever byte r2 is non-zero under the current 2.0 release. 
Normally, non-zero return codes can be treated as missing data, 
with zero return codes indicating operation complete. 
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Function 34: Write Random 



Entry Parameters: 



Register 
Registers 


C: 
DE: 


22H 

FCB Address 


Returned Value: 






Register 


A: 


Return Code 



The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is 
the target of the write has not yet been allocated, the allocation is 
performed before the write operation continues. As in the Read 
Random operation, the random record number is not changed as a 
result of the write. The logical extent number and current record 
positions of the file control block are set to correspond to the 
random record which is being written. Again, sequential read or 
write operations can commence following a random write, with the 
notation that the currently addressed record is either read or 
rewritten again as the sequential operation begins. You can also 
simply advance the random record position following each write 
to get the effect of a sequential write operation. Note that in 
particular, reading or writing the last record of an extent in 
random mode does not cause an automatic extent switch as it does 
in sequential mode. 



The error codes returned by a random write are identical to the 
random read operation with the addition of error code 05, which 
indicates that a new extent cannot be created due to directory 
overflow. 
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Function 35: Compute File Size 



Entry Parameters: 

Register 
Registers 



C: 23H 
DE: FCB Address 



Returned Value: 

Random Record Field Set 

When computing the size of a file, the DE register pair addresses 
an FCB in random mode format (bytes rO, r1 , and r2 are present). 
The FCB contains an unambiguous file name which is used in 
the directory scan. Upon return, the random record bytes contain 
the "virtual" file size which is, in effect, the record address of the 
record following the end of the file. If, following a call to function 
35, the high record byte r2 is 01 , then the file contains the 
maximum record count 65536. Otherwise, bytes rO and r1 constitute 
a 16-bit value (rO is the least significant byte, as before) which is 
the file size. 

Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end 
of file, then performing a sequence of random writes starting at the 
preset record address. 

The virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created in 
random mode and "holes" exist in the allocation, then the file 
may in fact contain fewer records than the size indicates. If, for 
example, only the last record of an eight megabyte file is written 
in random mode (i.e., record number 65535), then the virtual size 
in 65536 records, although only one block of data is actually 
allocated. 
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Function 36: Set Random Record 



Entry Parameters: 

Register 
Registers 



C: 24H 
DE: FCB Address 



Returned Value: 

Random Record Field Set 

The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been 
read or written sequentially to a particular point. The function can 
be useful in two ways. 

First, it is often necessary to initially read and scan a sequential 
file to extract the position of various "key" fields. As each key is 
encountered, function 36 is called to compute the random record 
position for the data corresponding to this key. If the data unit size 
is 128 bytes, the resulting record position is placed into a table 
with the key for later retrieval. After scanning the entire file and 
tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
using the corresponding random record number which was saved 
earlier. The scheme is easily generated when variable record 
lengths are involved since the program need only store the 
buffer-relative byte position along with the key and record number 
in order to find the exact starting position of the keyed data at a 
later time. 

A second use of function 36 occurs when switching from a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 is 
called which sets the record number, and subsequent random 
read and write operations continue from the selected point in the 
file. 
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Sample File-to-File Copy Program 



MOVE SECOND FILE NAME TO DFCB 



The program shown below provides a relatively simple example of 
file operations. The program source file is created as COPY.ASM 
using the CP/M ED program and then assembled using ASM or 
MAC, resulting in a "HEX" file. The LOAD program is then used 
to produce a COPY.COM file which executes directly under the 
CCP. The program begins by setting the stack pointer to a local 
area, and then proceeds to move the second name from the default 
area at 006CH to a 33-byte file control block called DFCB. The 
DFCB is then prepared for file operations by clearing the current 
record field. At this point, the source and destination FCB's are 
ready for processing since the SFCB at 005CH is properly set-up 
by the CCP upon entry to the COPY program. That is, the first 
name is placed into the default FCB, with the proper fields zeroed, 
including the current record field at 007CH. The program 
continues by opening the source file, deleting any existing 
destination file, and then creating the destination file. If all this is 
successful, the program loops at the label COPY until each 
record has been read from the source file and placed into the 
destination file. Upon completion of the data transfer, the destination 
file is closed and the program returns to the CCP command level 
by jumping to BOOT. 







SAMPLE FILE-TO-FILfc COPY FHUGHAM 
AT THE CCP LEVEL, THE COMMAND 








COPYA:X.YB:UV 






COPIES THE FILE NAMED X.Y FROM DRIVE 






A TO A FILE NAMED U.V ON DRIVE B. 


0000 = 


BOOT 


EQU 


0000 H 


SYSTEM REBOOT 


0005 = 


BDOS 


EQU 


0005 H 


BDOS ENTRY POINT 


005C = 


FCB1 


EQU 


005CH 


FIRST FILE NAME 


005C = 


SFCB 


EQU 


FCB1 


SOURCE FCB 


006C = 


FCB2 


EQU 


006CH 


SECOND FILE NAME 


0080 = 


DBUFF 


EQU 


0080 H 


DEFAULT BUFFER 


0100 = 


TPA 


EQU 


0100H 


BEGINNING OF TPA 


0009 = 


PRINTF 


EQU 


9 


PRINT BUFFER FUNC 


000 F = 


OPENF 


EQU 


15 


OPEN FILE FUNCa 


0010 = 


CLOSEF 


EQU 


16 


CLOSE FILE FUNCa 


0013 = 


DELETEF 


EQU 


19 


DELETE FILE FUNC* 


0014 = 


READF 


EQU 


20 


SEQUENTIAL READ 


0015 = 


WRITEF 


EQU 


21 


SEQUENTIAL WRITE 


0016 = 


MAKEF 


EQU 


22 


MAKE FILE FUNCs 


0100 




ORG 


TPA 


BEGINNING OF TPA 


0100 311B02 




LXI 


S P. STACK 


LOCAL STACK 



0151 11DA01 

0154 CD6E01 

0157 21BB01 

01 5A 3C 

015B CC6101 



015E 11CC01 



0161 0E09 
0163 CD0500 
0166 C30000 



0169 OEOF 



0103 OE10 

0105 116C00 

0108 21DA01 

010B 1A 

010C 13 

010D 77 

010E 23 

010F OD 

0110 C20B01 



0113 AF 

0114 32FA01 



0117 115C00 

011 A CD6901 

01 1D 118701 

0120 3C 

0121 CC6101 



0124 11DA01 

0127 CD7301 

01 2A 11DA01 

01 2D CD8201 

0130 119601 

0133 3C 

0134 CC6101 



0137 115C00 COPY: 

013A CD7801 

013D B7 

013E C25101 



0141 11DA01 

0144 CD7D01 

0147 11A901 

014A B7 

014B C46101 

014E C33701 



EOFILE: 



FINIS: 



MVI 


C.16 


HALF AN FCB 


LXI 


D.FCB2 


SOURCE OF MOVE 


LXI 


H.DFCB 


DESTINATION FCB 


LDAX 


D 


SOURCE FCB 


INX 


D 


READY NEXT 


MOV 


M.A 


DEST FCB 


INX 


H 


READY NEXT 


DCR 


C 


COUNT 16.0 


JNZ 


MFCB 


LOOP 16 TIMES 



NAME HAS BEEN MOVED. ZERO CR 

XRA A ; A = 00H 

STA DFCBCR ; CURRENT REC = 

SOURCE AND DESTINATION FCB S READY 



LXI 


D.SFCB 


: SOURCE FILE 


CALL 


OPEN 


; ERROR IF 255 


LXI 


D.NOFILE 


: READY MESSAGE 


INR 


A 


. 255 BECOMES 


CZ 


FINIS 


: DONE IF NO FILE 



SOURCE FILE OFEN, PREP DESTINATION 

LXI D.DFCB . DESTINATION 

CALL DELETE : REMOVE IF PRESENT 



LXI 

CALL 

LXI 

INR 

CZ 



D.DFCB 

MAKE 

D.NODIR 

A 

FINIS 



DESTINATION 
CREATE THE FILE 
READY MESSAGE 
255 BECOMES 
DONE IF NO DIR SPACE 



SOURCE FILE OPEN. DEST FILE OPEN 
COPY UNTIL END OF FILE ON SOURCE 



LXI D.SFCB 

CALL READ 

ORA A 

JNZ EOFILE 



SOURCE 

READ NEXT RECORD 
END OF FILE? 
SKIP WRITE IF SO 



NOT END OF FILE. WRITE THE RECORD 



LXI 

CALL 

LXI 

ORA 

CNZ 

JMP 



D.DFCB 

WRITE 

D. SPACE 

A 

FINIS 

COPY 



DESTINATION 
WRITE RECORD 
READY MESSAGE 
00 IF WRITE OK 
END IF SO 
LOOP UNTIL EOF 



END OF FILE, CLOSE DESTINATION 



LXI 

CALL 

LXI 

INR 

CZ 



D.DFCB 

CLOSE 

H.WRPROT 

A 

FINIS 



DESTINATION 
255 IF ERROR 
READY MESSAGE 
255 BECOMES 00 
SHOULDN'T HAPPEN 



OPEN: 



COPY OPERATION COMPLETE, END 

LXI D. NORMAL : READY MESSAGE 

: WRITE MESSAGE GIVEN BY DE. REBOOT 
MVI C.PRINTF 

CALL BDOS : WRITE MESSAGE 

JMP BOOT : REBOOT SYSTEM 

SYSTEM INTERFACE SUBROUTINES 
(ALL RETURN DIRECTLY FROM BDOS) 

MVI C, OPENF 
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016B 


C30500 




JMP 


BDOS 


016E 


0E10 


CLOSE: 


MVI 


C.CLOSEF 


0170 


C30500 




JMP 


BDOS 


0173 


0E13 


DELETE: 


MVI 


C.DELETEF 


0175 


C30500 




JMP 


BDOS 


0178 


0E14 


READ: 


MVI 


C.READF 


01 7A 


C30500 




JMP 


BDOS 


017D 


0E15 


WRITE: 


MVI 


C.WRITEF 


017F 


C30500 




JMP 


BDOS 


0182 


0E16 


MAKE: 


MVI 


C.MAKEF 


0184 


C30500 




JMP 


BDOS 



0187 6E6F20FNOFILE: 

0196 6E6F209NODIR' 

01 A9 6F7574FSPACE: 

01 BB 7772695WRPROT: 

01CC 636F700NORMAL: 



CONSOLE MESSAGES 

DB NO SOURCE FILES 

DB NO DIRECTORY SPACES 

DB OUT OF DATA SPACES 

DB WRITE PROTECTED-?* 

DB COPY COMPLETES 



01 DA 
01 FA 



01 FB 
021 B 



DFCB: 
DFCBCR 



STACK: 



DATA AREAS 
DS 33 

EQU DFCB + 32 



DS 



32 



DESTINATION FCB 
CURRENT RECORD 



16 LEVEL STACK 



Note that there are several simplifications in this particular 
program. First, there are no checks for invalid file names which 
could, for example, contain ambiguous references. This situation 
could be detected by scanning the 32 byte default area starting at 
location 005CH for ASCII question marks. A check should also 
be made to ensure that the file names have, in fact, been included 
(check locations 005DH and 006DH for non-blank ASCII characters). 
Finally, a check should be made to ensure that the source and 
destination file names are different. A speed improvement could be 
made by buffering more data on each read operation. One could, 
for example, determine the size of memory by fetching FBASE 
from location 0006H and use the entire remaining portion of 
memory for a data buffer. In this case, the programmer simply 
resets the DMA address to the next successive 1 28 byte area 
before each read. Upon writing to the destination file, the DMA 
address is reset to the beginning of the buffer and incremented 
by 128 bytes to the end as each record is transferred to the 
destination file. 
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Sample File Dump Utility 



The file dump program shown below is slightly more complex 
than the single copy program given in the previous section. The 
dump program reads an input file, specified in the CCP command 
line, and displays the content of each record in hexadecimal format 
at the console. Note that the dump program saves the CCP's 
stack upon entry, resets the stack to a local area, and restores the 
CCP's stack before returning directly to the CCP. Thus, the dump 
program does not perform warm start at the end of processing. 



DUMP PROGRAM READS INPUT FILE AND DISPLAYS HEX DATA 



0100 






ORG 100H 




0005 


_ 


BDOS 


EOU 0005H 


DOS ENTRY POINT 


0001 


= 


CONS 


EQU 1 


READ CONSOLE 


0002 


= 


TYPEF 


EQU 2 


TYPE FUNCTION 


0009 


:vi 


PRINTF 


EQU 9 


BUFFER PRINT ENTRY 


000 B 


= 


BRKF 


EQU 11 


BREAK KEY FUNCTION (TRUE IF CHAR 


000 F 


= 


OPENF 


EQU 15 


FILE OPEN 


0014 


= 


READF 


EQU 20 


READ FUNCTION 


005C 


= 


FCB 


EQU 5CH 


FILE CONTROL BLOCK ADDRESS 


0080 


= 


BUFF 


EQU 80H 


INPUT DISK BUFFER ADDRESS 








NON GRAPHIC CHARACTERS 


000 D 


= 


CR 


EQU ODH 


CARRIAGE RETURN 


000A 


"- 


LF 


EQU OAH 


LINE FEED 








FILE CONTROL BLOCK DEFINITIONS 


005C 


= 


FCBDN 


EQU FCB+0 


DISK NAME 


005 D 


= 


FCBFN 


EQU FCB+1 


FILE NAME 


0065 


= 


FCBFT 


EQU FCB+9 


DISK FILE TYPE (3 CHARACTERS) 


0068 


= 


FCBRL 


EQU FCB+12 


FILE S CURRENT REEL NUMBER 


006 B 


= 


FCBRC 


EQU FCB + 15 


FILES RECORD COUNT (0 TO 128) 


007C 


= 


FCBCR 


EQU FCB+32 


CURRENT(NEXT) RECORD NUMBER (0) 


007D 




FCBLN 


EQU FCB + 33 
SET UP STACK 


FCB LENGTH 


0100 


210000 




LXI H.O 




0103 


39 




DAD SP 










ENTRY STACK POINTER IN HL FROM THE CCP 


0104 


221502 




SHLD OLDSP 










SET SP TO LOCAL STACK AREA (RESTORED AT FINIS) 


0107 


315702 




LXI SP.STKTOP 










READ AND PRINT SUCCESSIVE BUFFERS 


01 OA 


CDC101 




CALL SETUP 


SET UP INPUT FILE 


010D 


FEFF 




CPI 255 


255 IF FILE NOT PRESENT 


010F 


C21B01 




JNZ OPENOK 


SKIP IF OPEN IS OK 








FILE NOT THERE. GIVE ERROR MESSAGE AND RETURN 


0112 


LLF301 




LXI D.OPNMSG 




0115 


CD9C01 




CALL ERR 




0118 


C35101 




JMP FINIS 


TO RETURN 






OPENOK: 


:OPEN OPERATION OK 


SET BUFFER INDEX TO END 


011B 


3E80 




MVI A,80H 




011D 


321302 




STA IBP 


SET BUFFER POINTER TO 80H 








HL CONTAINS NEXT ADDRESS TO PRINT 


0120 


210000 




LXI H.O 


START WITH 0000 
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GLOOP: 



0123 E5 

0124 CDA201 

0127 E1 

0128 DA5101 
012B 47 



012C 7D 

012D E60F 

012F C24401 

0132 CD7201 



;SAVE LINE POSITION 



;RECALL LINE POSITION 
;CARRY SET BY GNB IF END FILE 



PUSH H 

CALL GNB 

POP H 

JC FINIS 

MOV B.A 

PRINT HEX VALUES 

CHECK FOR LINE FOLD 

MOV A,L 

ANI OFH :CHECK LOW 4 BITS 

JNZ NONUM 

PRINT LINE NUMBER 

CALL CRLF 



0135 CD5901 



0138 OF 

0139 DA5101 



CHECK FOR BREAK KEY 

CALL BREAK 

ACCUM LSB = 1 IF CHARACTER READY 

RRC ;INTO CARRY 

JC FINIS ;DONT PRINT ANY MORE 



01 3C 7C 

01 3D CD8F01 

0140 7D 

0141 CD8F01 

0144 23 

0145 3E20 
0147 CD6501 
014A 78 
014B CD8F01 
01 4E C32301 



NONUM: 



MOV 


A.H 


CALL 


PHEX 


MOV 


A,L 


CALL 


PHEX 


INX 


H 


MVI 


A.' 


CALL 


PCHAR 


MOV 


A.B 


CALL 


PHEX 


JMP 


GLOOP 



;TO NEXT LINE NUMBER 



FINIS: 



0151 CD7201 

0154 2A1502 

0157 F9 

0158 C9 



0159 E5D5C5 

01 5C OEOB 

015E CDO500 

0161 C1D1E1 

0164 C9 



END OF DUMP. RETURN TO CCP 

(NOTE THAT A JMPTO0000H REBOOTS) 

CALL CRLF 

LHLD OLDSP 

SPHL 

STACK POINTER CONTAINS CCPS STACK LOCATION 

RET :TOTHECCP 



SUBROUTINES 

:CHECK BREAK KEY (ACTUALLY ANY KEY WILL DO) 

PUSH H' PUSH D! PUSH B: ENVIRONMENT SAVED 

MVI CBRKF 

CALL BDOS 

POP B' POP D! POP H: ENVIRONMENT RESTORED 

RET 



PCHAR: :PRINT A CHARACTER 

0165 E5D5C5 PUSH H' PUSH D' PUSH B: SAVED 

0168 0E02 MVI C.TYPEF 

016A 5F MOV E.A 

01 6B CD0500 CALL BDOS 

016E C1D1E1 POP B' POP D' POP H; RESTORED 

0171 C9 RET 



0172 3E0D 

0174 CD6501 

0177 3E0A 

0179 CD6501 

017C C9 



CRLF: 



MVI A.CR 

CALL PCHAR 

MVI A.LF 

CALL PCHAR 
RET 
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01 7D E60F 

01 7F FEOA 

0181 D28901 

0184 C630 

0186 C38B01 



;PRINT NIBBLE IN REG A 

ANI OFH :LOW4BITS 

CPI 10 

JNC P10 

LESS THAN OR EQUAL TO 9 

ADI 0' 

JMP PRN 



GREATER OR EQUAL TO 10 



0189 


C637 


P10: 


ADI A - 10 


018B 


CD6501 


PRN: 


CALL PCHAR 


018E 


C9 




RET 






PHEX: 


PRINT HEX CHAR IN REG A 


018F 


F5 




PUSH PSW 


0190 


OF 




RRC 


0191 


OF 




RRC 


0192 


OF 




RRC 


0193 


OF 




RRC 


0194 


CD7D01 




CALL PNIB PRINT NIBBLE 


0197 


F1 




POP PSW 


0198 


CD7D01 




CALL PNIB 


019B 


C9 




RET 



01 9C 0E09 
01 9E CD0500 
01A1 C9 



PRINT ERROR MESSAGE 

D.E ADDRESSES MESSAGE ENDING WITH "$' 

MVI CPRINTF PRINT BUFFER FUNCTION 

CALL BDOS 

RET 



GNB: 



01A2 3A1302 
01A5 FE80 
01A7 C2B301 



01AA CDCE01 

01AD B7 

01AE CAB301 

01B1 37 

01 B2 C9 



:GET NEXT BYTE 

LDA IBP 

CPI 80H 

JNZ GO 

READ ANOTHER BUFFER 



CALL DISKR 

ORA A :ZERO VALUE IF READ OK 

JZ GO :FOR ANOTHER BYTE 

END OF DATA, RETURN WITH CARRY SET FOR EOF 

STC 

RET 



01 B3 5F 

01 B4 1600 

01 B6 3C 

01 B7 321302 



01BA 218000 
01BD 19 



01BE 7E 



01BF B7 
01 CO C9 



:READ THE BYTE AT BUFF + REG A 

MOV E.A ;1S BYTE OF BUFFER INDEX 

MVI DO ;DOUBLE PRECISION INDEX TO DE 

INR A .INDEX = INDEX+1 

STA IBP PACK TO MEMORY 

POINTER IS INCREMENTED 

SAVE THE CURRENT FILE ADDRESS 

LXI H.BUFF 

DAD D 

ABSOLUTE CHARACTER ADDRESS IS IN H1 

MOV A.M 

BYTE IS IN THE ACCUMULATOR 

ORA A PESET CARRY BIT 

RET 



01C1 AF 
01C2 327C00 



:SETUPFILE 

OPEN THE FILE FOR INPUT 

XRA A :ZERO TO ACCUM 

STA FCBCR :CLEAR CURRENT RECORD 



01C5 115C00 
01C8 OEOF 



LXI 
MVI 



D.FCB 
C.OPENF 
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DISKR: 



01CA CD0500 
01CD C9 



01CE E5D5C5 

01 D1 115C00 

01D4 0E14 

01 D6 CD0500 

01D9 C1D1E1 

01 DC C9 



01 DD 46494C0SIGNON: 
01 F3 0D0A4E0OPNMSG: 



0213 IBP: 

0215 OLDSP: 



CALL BDOS 

255 IN ACCUM IF OPEN ERROR 

RET 

;READ DISK FILE RECORD 
PUSH H! PUSH D! PUSH B 
LXI D.FCB 

MVI CREADF 

CALL BDOS 

POP B! POP D! POP H 
RET 

FIXED MESSAGE AREA 

DB FILE DUMP VERSION 2.0$ 

DB CR.LF. NO INPUT FILE PRESENT ON DISKS 



VARIABLE AREA 
DS 2 

DS 2 

STACK AREA 
DS 64 



;INPUT BUFFER POINTER 
;ENTRY SP VALUE FROM CCP 



;RESERVE 32 LEVEL STACK 



STKTOP: 



Sample Random Access Program 



This manual is concluded with a rather extensive, but complete 
example of random access operation. The program listed below 
performs the simple function of reading or writing random records 
upon command from the terminal. Given that the program has been 
created, assembled, and placed into a file labelled RANDOM.COM, 
the CCP level command: 

RANDOM X.DAT 

starts the test program. The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 

next command? 

and is followed by operator input, terminated by a carriage return. 
The input commands take the form 

nW nR Q 



where n is an integer value in the range to 65535, and W, R, 
and Q are simple command characters corresponding to random 
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write, random read, and quit processing, respectively. If the W 
command is issued, the RANDOM program issues the prompt 

type data: 

The operator then responds by typing up to 127 characters, followed 
by a carriage return. RANDOM then writes the character string 
into the X.DAT file at record n. If the R command is issued, 
RANDOM reads record number n and displays the string value at 
the console. If the Q command is issued, the X.DAT file is closed, 
and the program returns to the console command processor. In 
the interest of brevity, the only error message is 

error, try again 

The program begins with an initialization section where the input 
file is opened or created, followed by a continuous loop at the 
label "ready" where the individual commands are interpreted. The 
default file control block at 005CH and the default buffer at 
0080H are used in all disk operations. The utility subroutines then 
follow, which contain the principal input line processor, called 
"readc." This particular program shows the elements of random 
access processing, and can be used as the basis for further 
program development. 





************* 


********' 


************************ 




* SAMPLE RANDOM ACCESS PROGRAM FOR CP/M 2.0 




....... 


****** 


......... 


,....,....,.,.,,.,...,.. 


0100 




ORG 


100H 


: BASE OF TPA 


0000 = 


REBOOT 


EQU 


OOOOH 


; SYSTEM REBOOT 


0005 = 


3DOS 


EQU 


0005 H 


;BDOS ENTRY POINT 


0001 = CONINP 


EQU 


1 


; CONSOLE INPUT FUNCTION 


0002 = CONOUT 


EQU 


2 


; CONSOLE OUTPUT FUNCTION 


0009 = 


^STRING 


EQU 


9 


; PRINT STRING UNTIL $ 


000A = RSTRING 


EQU 


10 


; READ CONSOLE BUFFER 


000C = VERSION 


EQU 


12 


; RETURN VERSION NUMBER 


000F = OPENF 


EQU 


15 


; FILE OPEN FUNCTION 


0010 = CLOSEF 


EQU 


16 


; CLOSE FUNCTION 


0016 = MAKEF 


EQU 


22 


; MAKE FILE FUNCTION 


0021 = READR 


EQU 


33 


; READ RANDOM 


0022 = WRITER 


EQU 


34 


; WRITE RANDOM 



005C 



EQU 



005CH 



DEFAULT FILE CONTROL BLOCK 
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007 D 
007 F 
0080 



RANREC EQU 
RANOVF EQU 
BUFF EQU 



FCB + 33 
FCB + 35 
0080H 



RANDOM RECORD POSITION 
HIGH ORDER (OVERFLOW) BYTE 
BUFFER ADDRESS 



000 D 
000A 



0100 31BC0 



CR 

LF 



EQU 
EQU 



ODH 
OAH 



: CARRIAGE RETURN 
LINE FEED 



LOAD SP. SET-UP FILE FOR RANDOM ACCESS 



LXI 



S P. STACK 



0103 OEOC 

0105 CD050 

0108 FE20 

010A D2160 

010D 111B0 

0110 CDDAO 

0113 C3000 



VERSION 2.0? 

MVI C. VERSION 

BDOS 

CPI 20H : VERSION 2.0 OR BETTER? 

JNC VERSOK 

BAD VERSION, MESSAGE AND GO BACK 

LXI DBADVER 

CALL PRINT 

JMP REBOOT 



VERSOK: 



0116 OEOF 

0118 11 SCO 

01 1B CD050 

01 1E 3C 

01 1F C2370 



CORRECT VERSION FOR RANDOM ACCESS 

MVI C.OPENF OPEN DEFAULT FCB 

LXI D.FCB 

CALL BDOS 

INR A : ERR 255 BECOMES ZERO 

JNZ READY 



0122 0E16 

0124 11 SCO 

0127 CD050 

012A 3C 

012B C2370 



CANNOT OPEN FILE. SO CREATE IT 

MVI C.MAKEF 

LXI D.FCB 

CALL BDOS 

INR A ; ERR 255 BECOMES ZERO 

READY 



012E 113A0 
0131 CDDAO 
0134 C3000 



CANNOT CREATE FILE. DIRECTORY FULL 

LXI D.NOSPACE 

CALL PRINT 

JMP REBOOT :BACKTOCCP 



LOOP BACK TO READY' AFTER EACH COMMAND 



FILE IS READY FOR PROCESSING 



0137 CDE50 

013A 227D0 

013D 217F0 

0140 3600 

0142 FE51 

0144 C2560 



0147 0E10 

0149 115C0 
014C CD050 
014F 3C 

0150 CAB90 
0153 C3000 



CALL 


READCOM 


; READ NEXT COMMAND 


SHLD 


RANREC 


; STORE INPUT RECORDS 


LXI 


H, RANOVF 




MVI 


M.O 


: CLEAR HIGH BYTE IF SET 


CPI 


Q' 


:QUIT? 


JNZ 


NOTQ 




QUIT PROCESSING. CLOSE FILE 


MVI 


C.CLOSEF 




LXI 


D.FCB 




CALL 


BDOS 




INR 


A 


;ERR 255 BECOMES 


JZ 


ERROR 


; ERROR MESSAGE. RETRY 


JMP 


REBOOT 


; BACK TO CCP 
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0156 FE57 
0158 C2890 



015B 114D0 

01 5E CDDAO 

0161 0E7F 

0163 21800 

0166 C5 

0167 E5 

0168 CDC20 
016B E1 
016C C1 
016D FEOD 
016F CA780 

0172 77 

0173 23 

0174 OD 

0175 C2660 



01 78 3600 



017A 0E22 

01 7C 115C0 

01 7F CD050 

0182 B7 

0183 C2B90 
0186 C3370 



END OF QUIT COMMAND. PROCESS WRITE 



NOTQ: 



RLOOP: 



ERLOOP 



NOT THE QUIT COMMAND. RANDOM WRITE? 
CPI W 

JNZ NOTW 

THIS IS A RANDOM WRITE. FILL BUFFER UNTIL CR 
LXI D.DATMSG 



CALL 

MVI 

LXI 



PRINT 
C127 
H.BUFF 



DATA PROMPT 

UP TO 127 CHARACTERS 

DESTINATION 



; READ NEXT CHARACTER TO BUFF 



PUSH 

PUSH 

CALL 

POP 

POP 

CPI 

JZ 



B 

H 

GETCHR 

H 

B 

CR 

ERLOOP 



SAVE COUNTER 
NEXT DESTINATION 
CHARACTER TO A 
RESTORE COUNTER 
RESTORE NEXT TO FILL 
END OF LINE? 



NOT END, STORE CHARACTER 



MOV 
INX 
DCR 
JNZ 



MA 

H 

C 

RLOOP 



NEXT TO FILL 
COUNTER GOES DOWN 
END OF BUFFER? 



END OF READ LOOP STORE 00 
MVI M.O 

WRITETHE RECORDTO SELECTED RECORD NUMBER 



MVI 


C.WRITER 




LXI 


D.FCB 




CALL 


BDOS 




ORA 


A 


: ERROR CODE ZERO? 


JNZ 


ERROR 


: MESSAGE IF NOT 


JMP 


READY 


. FOR ANOTHER RECORD 



0189 FE52 
018B C2B90 



END OF WRITE COMMAND. PROCESS READ 



NOTW 



NOT A WRITE COMMAND, READ RECORD? 

CPI R 

JNZ ERROR : SKIP IF NOT 



READ RANDOM RECORD 



018E 0E21 

0190 115C0 

0193 CD050 

0196 B7 

0197 C2B90 



019A CDCFO 

01 9D 0E80 

01 9F 21800 

01A2 7E 

01 A3 23 

01A4 E67F 



WLOOP: 



MVI 


C.READR 




LXI 


D.FCB 




CALL 


BDOS 




ORA 


A 


RETURN CODE 00? 


JNZ 


ERROR 




READ WAS SUCCESSFUL, WRITE TO CONSOLE 


CALL 


CRLF 


NEW LINE 


MVI 


C.128 


MAX 128 CHARACTERS 


LXI 


H.BUFF 


NEXT TO GET 


MOV 


A.M 


NEXT CHARACTER 


INX 


H 


NEXT TO GET 


AN I 


7FH 


MASK PARITY 
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01 A6 


CA370 


01 A9 


C5 


01 AA 


E5 


01AB 


FE20 


01AD 


D4C80 


01 BO 


E1 


01B1 


C1 


01 B2 


OD 


01 B3 


C2A20 


01 B6 


C3370 



01 B9 11590 
01 BC CDDAO 
01 BF C3370 



JZ 


READY 


PUSH 


B 


PUSH 


H 


CPI 




CNC 


PUTCHR 


POP 


H 


POP 


B 


DCR 


C 


JNZ 


WLOOP 


JMP 


READY 



FOR ANOTHER COMMAND IF 00 

SAVE COUNTER 

SAVE NEXT TO GET 

GRAPHIC? 

SKIP OUTPUT IF NOT 



;COUNT=COUNT-1 



END OF READ COMMAND, ALL ERRORS END-UP HERE 



ERROR: 



LXI D.ERRMSG 

CALL PRINT 

JMP READY 



UTILITY SUBROUTINES FOR CONSOLE I/O 



01C2 0E01 
01 C4 CD050 
01 C7 C9 



; READ NEXT CONSOLE CHARACTER TO A 
MVI CCONINP 

CALL BDOS 

RET 



01 C8 0E02 

01 CA 5F 

01 CB CD050 

01 CE C9 



PUTCHR: 



; WRITE CHARACTER FROM A TO CONSOLE 

MVI CCONOUT 

MOV E,A ; CHARACTER TO SEND 

CALL BDOS ; SEND CHARACTER 

RET 



CRLF: 



01CF 3E0D 

01 D1 CDC80 

01 D4 3E0A 

01 D6 CDC80 

01 D9 C9 



; SEND CARRIAGE RETURN LINE FEED 

MVI A.CR ; CARRIAGE RETURN 

CALL PUTCHR 

MVI A.LF : LINE FEED 

CALL PUTCHR 

RET 



01 DA 


D5 


PUSH 


01 DB 


CDCFO 


CALL 


01DE 


D1 


POP 


01 DF 


0E09 


MVI 


01E1 


CD050 


CALL 


01 E4 


C9 


RET 

READCOM: 

;REA 


01 E5 


116B0 


LXI 


01 E8 


CDDAO 


CALL 


01EB 


OEOA 


MVI 


01 ED 


117A0 


LXI 


01 FO 


CD050 


CALL 
COM! 


01 F3 


21000 


LXI 


01 F6 


117C0 


LXI 



PRINT THE BUFFER ADDRESSED BY DE UNTIL J 
D 

CRLF 

D : NEW LINE 

CPSTRING 
BDOS ; PRINT THE STRING 



READ THE NEXT COMMAND LINE TO THE CONBUF 
D, PROMPT 

PRINT ; COMMAND? 

CRSTRING 
D,CONBUF 

BDOS ;flEAD COMMAND LINE 

COMMAND LINE IS PRESENT, SCAN IT 

H,0 : START WITH 0000 

DCONLIN ; COMMAND LINE 
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01F9 1A 

01 FA 13 

01 FB B7 

01 FC C8 

01 FD D630 

01 FF FEOA 

0201 D2130 

0204 29 

0205 4D 

0206 44 

0207 29 

0208 29 

0209 09 
020A 85 
020B 6F 
020C D2F90 
020F 24 

0210 C3F90 



0213 C630 

0215 FE61 

0217 D8 

0218 E65F 
021 A C9 



READC: 



021 B 536F79 

023A 4E6F29 

024D 547970 

0259 457272 

026B 4E6570 



027A 21 
027B 
027C 
0021 = 



029C 
02BC 



LDAX D 

INX D 

ORA A 

RZ 

NOT ZERO, NUMERIC? 

SUI 0' 

CPI 10 ; 

JNC ENDRD 

ADD-IN NEXT DIGIT 



NEXT COMMAND CHARACTER 
TO NEXT COMMAND POSITION 
CANNOT BE END OF COMMAND 



CARRY IF NUMERIC 



DAD 

MOV 

MOV 

DAD 

DAD 

DAD 

ADD 

MOV 

JNC 

INR 

JMP 



H 

C.1 

B.H 

H 

H 

B 

1 

1,A 

READC 

H 

READC 



BC = 
*4 



«2 + *8 = 
+ DIGIT 



*10 



FOR ANOTHER CHAR 

OVERFLOW 

FOR ANOTHER CHAR 



END OF READ, RESTORE VALUE IN A 

ADI 0' ; COMMAND 

CPI A TRANSLATE CASE? 

RC 

LOWER CASE, MASK LOWER CASE BITS 

ANI 101$1111B 

RET 



STRING DATA AREA FOR CONSOLE MESSAGE 
BADVER: 



NOSPACE: 



DATMSG: 



ERRMSG: 



PROMPT: 



DB SORRY, YOU NEED CP/M VERSION 2$ 

DB NO DIRECTORY SPACES 

DB TYPE DATA: $ 

DB ERROR, TRY AGAIN. $ 

DB NEXT COMMAND? $ 



FIXED AND VARIABLE DATA AREA 



CONBUF: DB 

CONSIZE: DS 

CONLIN: DS 

CONLEN EQU 



STACK: 



DS 
END 



CONLEN 

1 

32 

$-CONSIZ 



32 



LENGTH OF CONSOLE BUFFER 
RESULTING SIZE AFTER READ 
LENGTH 32 BUFFER 



, 16 LEVEL STACK 
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Again, major improvements could be made to this particular 
program to enhance its operation. In fact, with some work, this 
program could evolve into a simple data base management 
system. One could, for example, assume a standard record size of 
1 28 bytes, consisting of arbitrary fields within the record. A 
program, called GETKEY, could be developed which first reads a 
sequential file and extracts a specific field defined by the operator. 
For example, the command 

GETKEY NAMES.DAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES.DAT and 
extract the "LASTNAME" field from each record, starting at 
position 10 and ending at character 20. GETKEY builds a table in 
memory consisting of each particular LASTNAME field, along 
with its 16-bit record number location within the file. The GETKEY 
program then sorts this list, and writes a new file, called 
LASTNAME. KEY, which is an alphabetical list of LASTNAME 
fields with their corresponding record numbers. (This list is called 
an "inverted index" in information retrieval parlance.) 

Rename the program shown above as QUERY, and massage it a 
bit so that it reads a sorted key file into memory. The command line 
might appear as: 

QUERY NAMES.DAT LASTNAME. KEY 



Instead of reading a number, the QUERY program reads an 
alphanumeric string which is a particular key to find in the 
NAMES.DAT data base. Since the LASTNAME. KEY list is sorted, 
you can find a particular entry quite rapidly by performing a 
"binary search," similar to looking up a name in the telephone 
book. That is, starting at both ends of the list, you examine the 
entry halfway in between and, if not matched, split either the upper 
half or the lower half for the next search. You'll quickly reach the 
item you're looking for (in log2(n) steps) where you'll find the 
corresponding record number. Fetch and display this record at 
the console, just as we have done in the program shown above. 

At this point you're just getting started. With a little more work, you 
can allow a fixed grouping size which differs from the 128 byte 
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record shown above. This is accomplished by keeping track of the 
record number as well as the byte offset within the record. 
Knowing the group size, you randomly access the record containing 
the proper group, offset to the beginning of the group within the 
record read sequentially until the group size has been exhausted. 



Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy 
several relationships, such as a LASTNAME between HARDY and 
LAUREL, and an AGE less than 45. Display all the records which 
fit this description. Finally, if your lists are getting too big to fit into 
memory, randomly access your key files from the disk as well. 
One note of consolation after all this work: if you make it through 
the project, you'll have no more need for this manual! 
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System Function Summary 







Input 


Output 


Func 


Function Name 


Parameters 


Results 





System Reset 


none 


none 


1 


Console Input 


none 


A=char 


2 


Console Output 


E=char 


none 


3 


Reader Input 


none 


A=char 


4 


Punch Output 


Eschar 


none 


5 


List Output 


Eschar 


none 


6 


Direct Console I/O 


see def 


see def 


7 


Get I/O Byte 


none 


A=IOBYTE 


8 


Set I/O Byte 


E=IOBYTE 


none 


9 


Print String 


DE=.Buffer 


none 


10 


Read Console Buffer 


DE=.Buffer 


see def 


11 


Get Console Status 


none 


A=00/FF 


12 


Return Version Number 


none 


HL=Version* 


13 


Reset Disk System 


none 


see def 


14 


Select Disk 


E=Disk Number 


see def 


15 


Open File 


DE-FCB 


A=DirCode 


16 


Close File 


DE^.FCB 


A=DirCode 


17 


Search for First 


DE=.FCB 


A=DirCode 


18 


Search for Next 


none 


A=Dir Code 


19 


Delete File 


DE=.FCB 


A=DirCode 


20 


Read Sequential 


DE-FCB 


A=ErrCode 


21 


Write Sequential 


DE-FCB 


A=ErrCode 


22 


Make File 


DE=.FCB 


A=DirCode 


23 


Rename File 


DE=.FCB 


A=DirCode 


24 


Return Login Vector 


none 


HL=Login Vect* 


25 


Return Current Disk 


none 


A=Cur Disk# 


26 


Set DMA Address 


DE=.DMA 


none 


27 


GetAddr(Alloc) 


none 


HL=.AIIoc 


28 


Write Protect Disk 


none 


see def 


29 


Get R/O Vector 


none 


HL= R/O Vect* 


30 


Set File Attributes 


DE-FCB 


see def 


31 


Get Addr (disk parms) 


none 


HL^.DPB 


32 


Set/Get User Code 


see def 


see def 


33 


Read Random 


DE-FCB 


A=Err Code 


34 


Write Random 


DE^.FCB 


A=ErrCode 


35 


Compute File Size 


DE-FCB 


rO, r1, r2 


36 


Set Random Record 


DE-FCB 


rO, ri,r2 



*Note the A=L, and B=H upon return 
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3 

CP/M Editor 



Introduction to ED 



ED is the context editor for CP/M, and is used to create and alter 
CP/M source files. ED is initiated in CP/M by typing 



ED 



<filename> 



<filename> ■ <filetype> 



In general, ED reads segments of the source file given by 
<filename> or <filename> • <filetype> into central memory, where 
the file is manipulated by the operator, and subsequently written 
back to disk after alterations. If the source file does not exist before 
editing, it is created by ED and initialized to empty. The overall 
operation of ED is shown in Figure 1 . 
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ED Operation 



ED operates upon the source file, denoted in Figure 1 by x.y, 
and passes all text through a memory buffer where the text can be 
viewed or altered (the number of lines which can be maintained 
in the memory buffer varies with the line length, but has a total 
capacity of about 6000 characters in a 16K CP/M system). Text 
material which has been edited is written onto a temporary work 
file under command of the operator. Upon termination of the 
edit, the memory buffer is written to the temporary file, followed by 
any remaining (unread) text in the source file. The name of the 
original file is changed from x.y to x.BAK so that the most recent 
previously edited source file can be reclaimed if necessary (see 
the CP/M commands ERASE and RENAME). The temporary file is 
changed from x.$$$ to x.y which becomes the resulting edited 
file. 

The memory buffer is logically between the source file and working 
file as shown in Figure 2. 



Text Transfer Functions 



Given that n is an integer value in the range through 65535, the 
following ED commands transfer lines of text from the source file 
through the memory buffer to the temporary (and eventually final) 
file: 
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Figure 1. Overall ED Operation 



Note 



Source 
Libraries 



R 



Source 
File 

X.Y 



Append 
(A) 



Memory 
Buffer 



[after edit 



insert 
(E) 



Backup 
File 

X.BAK 



Write 
(W) 



Temporary 
File 

X.$$$ 



type 
(T) 



after edit 
(E) 



£ 



o 



New 

Source 

File 

X.Y 



The ED program accepts both lower and upper case 
ASCII characters as input from the console. Single letter 
commands can be typed in either case. The U command 
can be issued to cause ED to translate lower case 
alphabetics to upper case as characters are filled to 
the memory buffer from the console. Characters are echoed 
as typed without translation, however. The — U command 
causes ED to revert to "no translation" mode. ED starts 
with an assumed — U in effect. 



Figure 2. Memory Buffer Organization 



Source File 



Memory Buffer 



Temporary File 



SP-» 



first line 



appended 
lines 



unprocessed 

source 

lines 



MP- 

nexf 
Append 



first line 



buffered 
text 



free 

memory 

space 




next 
Write 



first line 



processed 
text 



free 

file 

space 
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Figure 3. Logical Organization of Memory Buffer 



Memory Buffer 



first line 



current 
line CL 

last 
line 



crxlf; 

--<crx|f> 

A 

CP 

— <crx|f> 



:crxlf; 



nA<cr>* 



nW<cr> 



E<cr> 



H<cr> 



Append the next n unprocessed source 
lines from the source file at SP to the end of 
the memory buffer at MP. Increment SP and 
MP by n. 

Write the first n lines of the memory buffer 
to the temporary file free space. Shift the 
remaining lines n + 1 through MP to the top 
of the memory buffer. Increment TP by n. 

End the edit. Copy all buffered text to 
temporary file, and copy all unprocessed 
source lines to the temporary file. Rename 
files as described previously. 

Move to head of new file by performing 
automatic E command. Temporary file 
becomes the new source file, the memory 
buffer is emptied, and a new temporary file 
is created (equivalent to issuing an E 
command, followed by a reinvocation of ED 
using x.y as the file to edit). 



-cr represents the carriage-return key 
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0<cr> Return to original file. The memory buffer 

is emptied, the temporary file is deleted, 
and the SP is returned to position 1 of the 
source file. The effects of the previous 
editing commands are thus nullified. 

Q<cr> Quit edit with no file alterations, return 

to CP/M. 

There are a number of special cases to consider. If the integer n is 
omitted in any ED command where an integer is allowed, then 1 
is assumed. Thus, the commands A and W append one line and 
write 1 line, respectively. In addition, if a pound sign (#) is given 
in the place of n, then the integer 65535 is assumed (the largest 
value for n which is allowed). Since most reasonably sized 
source files can be contained entirely in the memory buffer, the 
command #A is often issued at the beginning of the edit to read 
the entire source file to memory. Similarly, the command #W writes 
the entire buffer to the temporary file. Two special forms of the A 
and W commands are provided as a convenience. The command 
OA fills the current memory buffer to at least half-full, while OW 
writes lines until the buffer is at least half empty. It should also be 
noted that an error is issued if the memory buffer size is exceeded. 
The operator may then enter any command (such as W) which does 
not increase memory requirements. The remainder of any partial 
line read during the overflow will be brought into memory on the 
next successful append. 



Memory Buffer Organization 



The memory buffer can be considered a sequence of source lines 
brought in with the A command from a source file. The memory 
buffer has an associated (imaginary) character pointer (CP) which 
moves throughout the memory buffer under command of the 
operator. The memory buffer appears logically as shown in Figure 3 
where the dashes represent characters of the source line of 
indefinite length, terminated by carriage return (<cr>) and line feed 
(<1f>) characters, and ^represents the imaginary character 
pointer. Note that the CP is always located ahead of the first 
character of the first line, behind the last character of the last 
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line, or between two characters. The current line CL is the source 
line which contains the CR 



Memory Buffer Operation 



Upon initiation of ED, the memory buffer is empty (i.e., CP is both 
ahead and behind the first and last character). The operator may 
either append lines (A command) from the source file, or enter the 
lines directly from the console with the insert command 

Kcr> 

ED then accepts any number of input lines, where each line 
terminates with a <cr> (the <lf> is supplied automatically), until a 
control-z (denoted by yz) is typed by the operator. The CP is 
positioned after the last character entered. The sequence 

Kcr> 

NOWISTHE<cr> 
TIME FOR<cr> 
ALL GOOD MEN<cr> 

Tz 

leaves the memory buffer as shown below 



NOWISTHE<crxlf> 

TIME FOR<crxlf> 

ALL GOOD MEN<cr> <lf>A 

Various commands can then be issued which manipulate the CP or 
display source text in the vicinity of the CP. The commands 
shown below with a preceding n indicate that an optional unsigned 
value can be specified. When preceded by =, the command can 
be unsigned, or have an optional preceding plus or minus sign. As 
before, the pound sign (#) is replaced by 65535. If an integer n is 
optional, but not supplied, then n=1 is assumed. Finally, if a plus 
sign is optional, but none is specified, then + is assumed. 



CP/M Editor 101 



± B <cr> move CP to beginning of memory buffer if 

+, and to bottom if -. 

± nC<cr> move CP by ± n characters (toward front of 
buffer if +), counting the <cr > <lf> as two 
distinct characters. 

± nD<cr> delete n characters ahead of CP if plus and 
behind CP if minus. 

±nK<cr> kill (i.e., remove) ±n lines of source text 
using CP as the current reference. If CP is 
not at the beginning of the current line when 
K is issued, then the characters before 
CP remain if + is specified, while the 
characters after CP remain if - is given in 
the command. 

± nL<cr> if n = 0, move CP to the beginning of 

the current line (if it is not already there). 
If n^O, first move the CP to the beginning 
of the current line, and then move it to the 
beginning of the line which is n lines down 
(if +) or up (if -). The CP will stop at the 
top or bottom of the memory buffer if too 
large a value is specified. 

± nT<cr> If n = then type the contents of the 

current line up to CP. If n = 1 then type the 
contents of the current line from CP to the 
end of the line. If n>1 then type the 
current line along with n-1 lines which 
follow, if + is specified. Similarly, if n>1 and 
- is given, type the previous n lines, up to 
the CP. The Break key can be depressed to 
abort long type-outs. 

±n<cr> equivalent to ±nLT, which moves up or down 

and types a single line. 
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Command Strings 



Any number of commands can be typed contiguously (up to the 
capacity of the CP/M console buffer), and are executed only 
after the <cr> is typed. Thus, the operator may use the CP/M 
console command functions to manipulate the input command. 

Rubout remove the last character 

Control-X delete the entire line 

Control-C re-initialize the CP/M System 

Control-E return carriage for long lines without trans- 

mitting buffer (max 128 chars) 

Suppose the memory buffer contains the characters shown in the 
previous section, with the CP following the last character of the 
buffer. The command strings shown below produce the results 
shown to the right. 



Command 
String 



Effect 



Resulting Memory Buffer 



B2T<cr> move to beginning of 

buffer and type 2 lines: 
"NOW IS THE 
TIME FOR" 

5C0T<cr> move CP 5 characters 
and type the beginning 
of the line "NOW I" 

2L-T<cr> move two lines down 

and type previous line 
"TIME FOR" 

-L#K<cr> move up one line, 
delete 65535 lines 
which follow 



*NOWISTHE<crX|f> 
TIME FOR<cr><lf> 
ALL GOOD MEN<cr> <lf> 



NOW I *STHE<crx|f> 



NOWISTHE<cr><lf> 
TIME FOR<crx|f> 
a ALL GOOD M EN<cr> <lf> 

NOWISTHE<crx|f>A 
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Command 
String 



Effect 



Resulting Memory Buffer 



Kcr> 

TIMETCKcr; 

INSERT<cr> 



insert two lines 
of text 



NOWISTHE<cr; 
TIMETO<crx|f 
INSERT<crx|f:; 



<lf; 



-2L#T<cr> move up two lines, and 
type 65535 lines ahead 
of CP "NOW IS THE" 

;cr> move down one line 

and type one line 
"INSERT" 



NOWISTHE<crxlf: 



TIMETO<cr: 
INSERT<cr> 



><lf: 
<lf> 



NOWISTHE<crx|f: 

TIMETO<crx|f>A 

INSERT<crxlf> 



Text Search and Alteration 



ED also has a command which locates strings within the memory 
buffer. The command takes the form 



nF c,Co 



:cr> 

Tz 



where C, through c k represent the characters to match 
followed by either a <cr> or control-z.* ED starts at the current 
position of CP and attempts to match all k characters. The match 
is attempted n times, and if successful, the CP is moved directly 
after the character c k . If the n matches are not successful, the 
CP is not moved from its initial position. Search strings can include 
Tl (control-l), which is replaced by the pair of symbols <cr> <lf>. 



*The control-z is used if additional commands will be typed following the "z. 
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The following commands illustrate the use of the F command: 



Command 
String 



Effect 



Resulting Memory Buffer 



B#T<cr> move to beginning 

and type entire 
buffer 

FS T<cr> find the end of 
the string "S T" 

FITzOTT find the next "I" and 

type to the CP then 
type the remainder of 
the current line: 
"TIME FOR" 



A p NOWISTHE<crxlf> 
TIME FOR<crxlf> 
ALL GOOD MEN<crxlf> 



NOWISTA p HE<cr>- 



:lf> 



NOWISTHE<crxlf> 
TI^ME FOR<crxlf> 
ALL GOOD MEN<cr> <lf> 



An abbreviated form of the insert command is also allowed, 
which is often used in conjunction with the F command to make 
simple textural changes. The form is: 

I c^j . . . c n Tz or 
I c-,c 2 . . . c n <cr> 

where ^ through c n are characters to insert. If the insertion 
string is terminated by a Tz, the characters C, through 
c n are inserted directly following the CP, and the CP is moved 
directly after character c n . The action is the same if the command 
is followed by a <cr> except that a <cr> <lf> is automatically 
inserted into the text following character c n . Consider the following 
command sequences as examples of the F and I commands: 
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Command 
String 



Effect 



Resulting Memory Buffer 



THIS ISftNOWTHE<crxlf> 

TIME FOR<cr><lf> 

ALL GOOD MEN<cr> <lf> 

THIS IS NOWTHE<cr><lf> 
PLACEA p FOR<cr><lf> 
ALL GOOD MEN<cr><lf> 

THIS IS NOWTHE<cr> <lf> 
PLACE FOR<cr><lf> 
' ALL CHANG ESA,<cr> <lf> 



BITHIS ISTz<cr> 

Insert "THIS IS" 
at the beginning 
of the text 

FTIMETz-4DIPLACETz<cr> 

find "TIME" and delete 
it; then insert "PLACE" 

3FOTz-3D5DICHANGEST<cr> 

find third occurrence of 
"O" (i.e., the second "O' 
in GOOD), delete pre- 
vious 3 characters; then 
insert "CHANGES" 

-8CIS0URCE<cr> 

move back 8 characters THIS IS NOWTHE<crxlf> 
and insert the line PLACE FOR<cr> <lf> 

"SOURCE<cr> <lf>" ALL SOURCE<cr> <lf> 

A p CHANGES<crxlf> 

ED also provides a single command which combines the F and I 
commands to perform simple string substitutions. The command 
takes the form 



nSc,c 2 . . .c k tzd 1 d 2 



<cr> 

Tz 



and has exactly the same effect as applying the command string 



<cr> 
Fc^g. . .c k Tz— kDld 1 d 2 . . -d m ] ^ z 



a total of n times. That is, ED searches the memory buffer starting 
at the current position of CP and successively substitutes the 
second string for the first string until the end of buffer, or until 
the substitution has been performed n times. 
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As a convenience, a command similar to F is provided by ED which 
automatically appends and writes lines as the search proceeds. 
The form is 



n N dc 2 . . . c k 



<cr> 

Tz 



which searches the entire source file for the nth occurrence of the 
string dc 2 . . . c k (recall that F fails if the string cannot be found in 
the current buffer). The operation of the N command is precisely 
the same as F except in the case that the string cannot be found 
within the current memory buffer. In this case, the entire memory 
contents is written (i.e., an automatic #W is issued). Input lines are 
then read until the buffer is at least half full, or the entire source 
file is exhausted. The search continues in this manner until the 
string has been found n times, or until the source file has been 
completely transferred to the temporary file. 

A final line editing function, called the juxtaposition command takes 
the form 



nJc,c 2 ...c k Tz d,d 2 . . . d m Tz e^ ... e c 



<cr> 

Tz 



with the following action applied n times to the memory buffer: 
search from the current CP for the next occurrence of the string 
do, . . . c k . If found, insert the string d,,d 2 . . . d m> and move CP to 
follow d m . Then delete all characters following CP up to (but not 
including) the string e u e 2 , • ■ ■ e q , leaving CP directly after d m . If 
e-i,e 2 , . . . e q cannot be found, then no deletion is made. If the 
current line is 

±NOW IS THE TIME<cr><lf> 
Then the command 

JW TzWHATTzTKcr> 
results in 



NOW WHAT A<crx|f> 
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(Recall that Tl represents the pair <cr> <lf> in search and 
substitution strings.) 

It should be noted that the number of characters allowed by 
ED in the F,S,N, and J commands is limited to 100 symbols. 



Source Libraries 



ED also allows the inclusion of source libraries during the editing 
process with the R command. The form of this command is 

R f^ . . f n Tz or 
R f^ . . f n <cr> 

where ij z . . f n is the name of a source file on the disk with an 
assumed filetype of LIBIED reads the specified file, and places 
the characters into the memory buffer after CP, in a manner 
similar to the I command. Thus, if the command 

RMACRO<cr> 

is issued by the operator, ED reads from the file MACRO. LIB 
until the end-of-file, and automatically inserts the characters into 
the memory buffer. 



Repetitive Command Execution 



The macro command M allows the ED user to group ED commands 
together for repeated evaluation. The M command takes the form: 



n M dc 2 



<cr> 

tz 



where c^ . . . c k represent a string of ED commands, not including 
another M command. ED executes the command string n times 
if n>1 . If n=0 or 1 , the command string is executed repetitively until 
an error condition is encountered (e.g., the end of the memory 
buffer is reached with an F command). 
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As an example, the following macro changes all occurrences of 
GAMMA to DELTA within the current buffer, and types each line 
which is changed: 

MFGAMMATz-5DIDELTATzOTT<cr> 

or equivalently 

MSGAMMATzDELTATzOTT<cr> 



ED Error Conditions 



On error conditions, ED prints the last character read before the 
error, along with an error indicator: 



? 
> 

# 
O 



unrecognized command 

memory buffer full (use one of the 
commands D, K, N, S, or W to remove 
characters), F, N, or S strings too long. 

cannot apply command the number of times 
specified (e.g., in F command) 

cannot open LIB file in R command 



Cyclic redundancy check (CRC) information is written with each 
output record under CP/M in order to detect errors on subsequent 
read operations. If a CRC error is detected, CP/M will type 

PERM ERR DISKd 

where d is the currently selected drive (A, B ). The operator 

can choose to ignore the error by typing any character at the 
console (in this case, the memory buffer data should be examined 
to see if it was incorrectly read), or the user can reset the 
system and reclaim the backup file, if it exists. The file can 
be reclaimed by first typing the contents of the BAK file to 
ensure that it contains the proper information. 

TYPE x.BAK<cr> 
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where x is the file being edited. Then remove the primary file: 

ERA x.y<cr> 
and rename the BAK file: 

REN x.y=x.BAK<cr> 
The file can then be re-edited, starting with the previous system. 

Summary of Control Characters 



The following table summarizes the Control characters and 
commands available in ED: 



Control Character 


Function 


Tc 


system reboot 


Te 


physical <cr><lf> (not actually 
entered in command) 


Ti 


logical tab (cols 1,8, 15 ) 


Tl 


logical <cr> <lf> in search 
and substitute strings 


Tx 


line delete 


Tz 


string terminator 


rubout 


character delete 


break 


discontinue command 
(e.g., stop typing) 
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Summary of ED Commands 



Command 


Function 


nA 


append lines 


±B 


begin bottom of buffer 


±nC 


move character positions 


±nD 


delete characters 


E 


end edit and close files 




(normal end) 


nF 


find string 


H 


end edit, close and reopen files 


I 


insert characters 


nJ 


place strings in juxtaposition 


^nK 


kill lines 


±nL 


move down/up lines 


nM 


macro definition 


nN 


find next occurrence with 




autoscan 





return to original file 


-nP 


move and print pages 


Q 


quit with no file changes 


R 


read library file 


nS 


substitute strings 


±nT 


type lines 


-U 


translate lower to upper case 




if U, no translation if -U 


nW 


write lines 


nZ 


sleep 


±n<cr> 


move and type (±nl_T) 
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ED Text Editing Commands 



The ED context editor contains a number of commands which 
enhance its usefulness in text editing. The improvements are found 
in the addition of line numbers, free space interrogation, and 
improved error reporting. 

The context editor issued with CP/M produces absolute line number 
prefixes when the "V" (Verify Line Numbers) command is issued. 
Following the V command, the line number is displayed ahead of 
each line in the format: 

nnnnn: 

where nnnnn is an absolute line number in the range 1 to 65535. 
If the memory buffer is empty, or if the current line is at the end 
of the memory buffer, then nnnnn appears as 5 blanks. 

The user may reference an absolute line number by preceding any 
command by a number followed by a colon, in the same format 
as the line number display. In this case, the ED program moves 
the current line reference to the absolute line number, if the 
line exists in the current memory buffer. Thus the command 

345:T 

is interpreted as "move to absolute line 345, and type the line." 
Note that absolute line numbers are produced only during the 
editing process, and are not recorded with the file. In particular, 
the line numbers will change following a deleted or expanded 
section of text. 

The user may also reference an absolute line number as a 
backward or forward distance from the current line by preceding 
the absolute line number by a colon. Thus, the command 

:400T 



is interpreted as "type from the current line number through the 



112 CP/M Reference Manual 



line whose absolute number is 400.'' Combining the two line 
reference forms, the command 

345::400T 

for example, is interpreted as "move to absolute line 345, then 
type through absolute line 400." Note that absolute line 
references of this sort can precede any of the standard ED 
commands. 

A special case of the V command, "OV," prints the memory 
buffer statistics in the form: 

free/total 

where "free" is the number of free bytes in the memory buffer 
(in decimal), and "total'' is the size of the memory buffer. 

ED also includes a "block move" facility implemented through 
the "X" (Xfer) command. The form 



nX 



transfers the next n lines from the current line to a temporary 
file called 



X$$$$$$$.LIB 

which is active only during the editing process. In general, 
the user can reposition the current line reference to any portion 
of the source file and transfer lines to the temporary file. The 
transferred lines accumulate one after another in this file, and can 
be retrieved by simply typing: 

R 

which is the trivial case of the library read command. In this 
case, the entire transferred set of lines is read into the memory 
buffer. Note that the X command does not remove the transferred 
lines from the memory buffer, although a K command can be used 
directly after the X, and the R command does not empty the 
transferred line file. That is, given that a set of lines has been 
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transferred with the X command, they can be re-read any number 
of times back into the source file. The command 

OX 

is provided, however, to empty the transferred line file. 

Note that upon normal completion of the ED program through 
Q or E, the temporary LIB file is removed. If ED is aborted through 
Control-C, the LIB file will exist if lines have been transferred, 
but will generally be empty (a subsequent ED invocation will erase 
the temporary file). 

Due to common typographical errors, ED requires several 
potentially disastrous commands to be typed as single letters, 
rather than in composite commands. The commands 

E (end), H (head), O (original), Q (quit) 
must be typed as single letter commands. 
ED also prints error messages in the form 

BREAK "x'ATc 

where x is the error character, and c is the command where the 
error occurred. 
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Introduction 



The CP/M assembler reads assembly language source files from 
the diskette, and produces 8080 machine language in Intel hex 
format. The CP/M assembler is initiated by typing 



or 



ASM filename 
ASM filename. parms 



In both cases, the assembler assumes there is a file on the diskette 
with the name 

filename. ASM 

which contains an 8080 assembly language source file. The first 
and second forms shown above differ only in that the second form 
allows parameters to be passed to the assembler to control 
source file access and hex and print file destinations. 

In either case, the CP/M assembler loads, and prints the message 

CP/M ASSEMBLER VER n.n 

where n.n is the current version number. In the case of the first 
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command, the assembler reads the source file with assumed file 
type "ASM" and creates two output files. 



and 



filename. HEX 
filename. PRN 



The "HEX" file contains the machine code corresponding to the 
original program in Intel hex format, and the "PRN" file contains 
an annotated listing showing generated machine code, error flags, 
and source lines. If errors occur during translation, they will be 
listed in the PRN file as well as at the console. 

The second command form can be used to redirect input and 
output files from their defaults. In this case, the "parms" portion 
of the command is a three letter group which specifies the origin of 
the source file, the destination of the hex file, and the destination 
of the print file. The form is 

filename. p1p2p3 

where p1 , p2, and p3 are single letters 



p1: A,B, ..., Y 



p2: A,B, ..., Y 



p3: A,B Y 

X 

Z 

Thus, the command 
ASM X.AAA 



designates the disk name which contains 
the source file 

designates the disk name which will 

receive the hex file 

skips the generation of the hex file 

designates the disk name which will 
receive the print file 
places the listing at the console 
skips generation of the print file 



indicates that the source file (X.ASM) is to be taken from disk A, 
and that the hex (X.HEX) and the print (X.PRN) files are to be 
created also on disk A. This form of the command is implied if 
the assembler is run from disk A. That is, given that the operator is 
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currently addressing disk A, the above command is equivalent to 

ASMX 
The command 

ASM X.ABX 

indicates that the source file is to be taken from disk A, the hex 
file is placed on disk B, and the listing file is to be sent to the 
console. The command 

ASMX.BZZ 

takes the source file from disk B, and skips the generation of the 
hex and print files. (This command is useful for fast execution of 
the assembler to check program syntax.) 

The source program format is compatible with both the Intel 
8080 assembler (macros are not currently implemented in the 
CP/M assembler, however) as well as the Processor Technology 
Software Package #1 assembler. That is, the CP/M assembler 
accepts source programs written in either format. There are 
certain extensions in the CP/M assembler which make it somewhat 
easier to use. These extensions are described below. 



Program Format 



An assembly language program acceptable as input to the 
assembler consists of a sequence of statements of the form 



line # label 



operation operand ;comment 



where any or all of the fields may be present in a particular 
instance. Each assembly language statement is terminated with 
a carriage return and line feed (the line feed is inserted automatically 
by the ED program), or with the character"!" which is treated as 
an end-of-line by the assembler (thus, multiple assembly language 
statements can be written on the same physical line if separated 
by exclamation symbols). 
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The line# is an optional decimal integer value representing the 
source program line number, which is allowed on any source line 
to maintain compatibility with the Processor Technology format. In 
general, these line numbers will be inserted if a line-oriented 
editor is used to construct the original program, and thus ASM 
ignores this field if present. 

The label field takes the form 



or 



identifier 
identifier: 



and is optional, except where noted in particular statement 
types. The identifier is a sequence of alphanumeric characters 
(alphabetics and numbers), where the first character is alphabetic. 
Identifiers can be freely used by the programmer to label elements 
such as program steps and assembler directives, but cannot 
exceed 16 characters in length. All characters are significant in an 
identifier, except for the embedded dollar symbol ($) which can 
be used to improve readability of the name. Further, all lower case 
alphabetics are treated as if they were upper case. Note that the 
":" following the identifier in a label is optional. Thus, the 
following are all valid instances of labels 

x xy long$name 

x : y x 1 : longer$named$data: 

X1Y2 X1x2 x234$5678$9012$3456: 

The operation field contains either an assembler directive, or 
pseudo operation, or an 8080 machine operation code. The 
pseudo operations and machine operation codes are described 
below. 



The operand field of the statement, in general, contains an 
expression formed out of constants and labels, along with arithmetic 
and logical operations on these elements. Again, the complete 
details of properly formed expressions are given below. 

The comment field contains arbitrary characters following the ";" 
symbol until the next real or logical end-of-line. These characters 
are read, listed, and otherwise ignored by the assembler. In order 
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to maintain compatibility with the Processor Technology assembler, 
the CP/M assembler also treats statements which begin with a 
"*" in column one as comment statements, which are listed and 
ignored in the assembly process. Note that the Processor 
Technology assembler has the side effect in its operation of ignoring 
the characters after the operand field has been scanned. This 
causes an ambiguous situation when attempting to be compatible 
with Intel's language, since arbitrary expressions are allowed in 
this case. Hence, programs which use this side effect to introduce 
comments, must be edited to place a ";" before these fields in 
order to assemble correctly. 

The assembly language program is formulated as a sequence of 
statements of the above form, terminated optionally by an END 
statement. All statements following the END are ignored by the 
assembler. 



Forming the Operand 



In order to completely describe the operation codes and pseudo 
operations, it is necessary to first present the form of the operand 
field, since it is used in nearly all statements. Expressions in the 
operand field consist of simple operands (labels, constants, and 
reserved words), combined in properly formed subexpressions 
by arithmetic and logical operators. The expression computation is 
carried out by the assembler as the assembly proceeds. Each 
expression must produce a 1 6-bit value during the assembly. 
Further, the number of significant digits in the result must not 
exceed the intended use. That is, if an expression is to be used in a 
byte move immediate instruction, then the most significant 8 bits 
of the expression must be zero. The restrictions on the expression 
significance are given with the individual instructions. 



Labels 

As discussed above, a label is an identifier which occurs on a 
particular statement. In general, the label is given a value determined 
by the type of statement which it precedes. If the label occurs on a 
statement which generates machine code or reserves memory 
space (e.g., a MOV instruction, or a DS pseudo operation), then the 



CP/M Assembler 121 



label is given the value of the program address which it labels. If 
the label precedes an EQU or SET, then the label is given the value 
which results from evaluating the operand field. Except for the 
SET statement, an identifier can label only one statement. 

When a label appears in the operand field, its value is substituted 
by the assembler. This value can then be combined with other 
operands and operators to form the operand field for a particular 
instruction. 

Numeric Constants 

A numeric constant is a 16-bit value in one of several bases. The 
base, called the radix of the constant, is denoted by a trailing radix 
indicator. The radix indicators are 

B binary constant (base 2) 

octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 

Q is an alternate radix indicator for octal numbers since the letter O 
is easily confused with the digit 0. Any numeric constant which 
does not terminate with a radix indicator is assumed to be a 
decimal constant. 



A constant is thus composed as a sequence of digits, followed by 
an optional radix indicator, where the digits are in the appropriate 
range for the radix. That is binary constants must be composed 
of and 1 digits, octal constants can contain digits in the range 
0—7, while decimal constants contain decimal digits. Hexadecimal 
constants contain decimal digits as well as hexadecimal digits A 
(10D), B(11D), C(12D), D(13D), E(14D), and F(15D). Note that 
the leading digit of a hexadecimal constant must be a decimal digit 
in order to avoid confusing a hexadecimal constant with an 
identifier (a leading will always suffice). A constant composed in 
this manner must evaluate to a binary number which can be 
contained within a 16-bit counter, otherwise it is truncated on the 
right by the assembler. Similar to identifiers, imbedded "$" are 
allowed within constants to improve their readability. Finally, the 
radix indicator is translated to upper case if a lower case letter is 
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encountered. The following are all valid instances of numeric 
constants 



1234 


1234D 


1100B 


1 111 $0000$ 111 1 $0000B 


1234H 


OFFEH 


33770 


33$77$22Q 


33770 


0fe3h 


1234d 


Offffh 



Reserved Words 

There are several reserved character sequences which have 
predefined meanings in the operand field of a statement. The 
names of 8080 registers are given below, which, when encountered, 
produce the value shown to the right. 



A 


7 


B 





C 


1 


D 


2 


E 


3 


H 


4 


L 


5 


M 


6 


SP 


6 


PSW 


6 



(Again, lower case names have the same values as their upper case 
equivalents.) Machine instructions can also be used in the 
operand field, and evaluate to their internal codes. In the case of 
instructions which require operands, where the specific operand 
becomes a part of the binary bit pattern of the instruction (e.g., 
MOV A,B), the value of the instruction (in this case MOV) is the 
bit pattern of the instruction with zeroes in the optional fields (e.g., 
MOV produces 40H). 



When the symbol "$" occurs in the operand field (not imbedded 
within identifiers and numeric constants) its value becomes the 
address of the text instruction to generate, not including the 
instruction contained within the current logical line. 
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String Constants 

String constants represent sequences of ASCII characters, and are 
represented by enclosing the characters within apostrophe 
symbols ('). All strings must be fully contained within the current 
physical line (thus allowing "!" symbols within strings), and must 
not exceed 64 characters in length. The apostrophe character itself 
can be included within a string by representing it as a double 
apostrophe (the keystrokes"), which becomes a single apostrophe 
when read by the assembler. In most cases, the string length is 
restricted to either one or two characters (the DB pseudo operation 
is an exception), in which case the string becomes an 8 or 16 bit 
value, respectively. Two character strings become a 16-bit constant, 
with the second character as the low order byte, and the first 
character as the high order byte. 

The value of a character is its corresponding ASCII code. There is 
no case translation within strings, and thus both upper and lower 
case characters can be represented. Note however, that only 
graphic (printing) ASCII characters are allowed within strings. 
Valid strings are 

A 'AB' ab' 'c' 

'a'" 
Walla Walla Wash.' 
She said "Hello" to me.' 
I said "Hello" to her.' 



Arithmetic and Logical Operators 

The operands described above can be combined in normal algebraic 
notation using any combination of properly formed operands, 
operators, and parenthesized expressions. 

The operators recognized in the operand field are 



a+b 
a-b 



unsigned arithmetic sum of a and b 
unsigned arithmetic difference between 
a and b 
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+b 

-b 

a * b 

a/b 

aMODb 

NOTb 



aANDb 
a OR b 
aXORb 
aSHLb 

aSHRb 



unary plus (produces b) 

unary minus (identical to — b) 

unsigned magnitude multiplication of a and b 

unsigned magnitude division of a by b 

remainder after a/ b 

logical inverse of b (all O's become 1 s, 1 s 

become O's), where b is considered a 

16-bit value 

bit-by-bit logical and of a and b 

bit-by-bit logical or of a and b 

bit-by-bit logical exclusive or of a and b 

the value which results from shifting a to the 

left by an amount b, with zero fill 

the value which results from shifting a to 

the right by an amount b, with zero fill 



In each case, a and b represent simple operands (labels, numeric 
constants, reserved words, and one or two character strings), or 
fully enclosed parenthesized subexpressions such as 



10+20 10h+37Q 


L1 /3 (L2^4)SHR3 


;'a' and 5fh) + '0' 


(B''B)0R(PSW+M: 


(1-(2+c))shr(A-(B+1)) 





Note that all computations are performed at assembly time as 
16-bit unsigned operations. Thus, -1 is computed as 0-1 which 
results in the value Offffh (i.e., all 1 s). The resulting expression 
must fit the operation code in which it is used. If, for example, the 
expression is used in a ADI (add immediate) instructions, then 
the high order eight bits of the expression must be zero. As a 
result, the operation "ADI — 1" produces an error message (-1 
becomes Offffh which cannot be represented as an 8 bit value), 
while ADI (-1 ) AND OFFH" is accepted by the assembler since 
the AND" operation zeroes the high order bits of the expression. 
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Precedence of Operators 

As a convenience to the programmer, ASM assumes that operators 
have a relative precedence of application which allows the 
programmer to write expressions without nested levels of 
parentheses. The resulting expression has assumed parentheses 
which are defined by the relative precedence. The order of 
application of operators in unparenthesized expressions is listed 
below. Operators listed first have highest precedence (they are 
applied first in an unparenthesized expression), while operators 
listed last have lowest precedence. Operators listed on the same 
line have equal precedence, and are applied from left to right as 
they are encountered in an expression 

*/MODSHLSHR 

NOT 
AND 
ORXOR 

Thus, the expressions shown to the left below are interpreted by 
the assembler as the fully parenthesized expressions shown to the 
right below 



a*b H 

a + b * c 

aMODb*cSHLd 

a OR b AND NOT c + d SHL e 



(a * b) -+- c 
a + (b * c) 

((aMODb)*c)SHI_d 
a OR (b AND (NOT (c + 



(dSHLe)))) 



Balanced parenthesized subexpressions can always be used to 
override the assumed parentheses, and thus the last expression 
above could be rewritten to force application of operators in a 
different order as 

(a OR b) AND (NOT c) + d SHL e 

resulting in the assumed parentheses 

(a OR b) AND ((NOT c) + (d SHL e)) 



Note that an unparenthesized expression is well-formed only if 
the expression which results from inserting the assumed 
parentheses is well-formed. 
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Assembler Directives 



Assembler directives are used to set labels to specific values 
during the assembly, perform conditional assembly, define storage 
areas, and specify starting addresses in the program. Each assembler 
directive is denoted by a "pseudo operation" which appears in 
the operation field of the line. The acceptable pseudo operations 
are 

ORG set the program or data origin 

END end program, optional start address 

EQU numeric "equate" 

SET numeric "set" 

IF begin conditional assembly 

ENDIF end of conditional assembly 

DB define data bytes 

DW define data words 

DS define data storage area 

The ORG Directive 

The ORG statement takes the form 



label 



ORG 



expression 



where "label" is an optional program label, and expression is a 
16-bit expression, consisting of operands which are defined 
previous to the ORG statement. The assembler begins machine 
code generation at the location specified in the expression. 
There can be any number of ORG statements within a particular 
program, and there are no checks to ensure that the programmer 
is not defining overlapping memory areas. Note that most programs 
written for the CP/M system begin with an ORG statement of the 
form 

ORG 100H 



which causes machine code generation to begin at the base of the 
CP/M transient program area. If a label is specified in the ORG 
statement, then the label is given the value of the expression (this 
label can then be used in the operand field of other statements 
to represent this expression). 
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The END Directive 

The END statement is optional in an assembly language program, 
but if it is present it must be the last statement (all subsequent 
statements are ignored in the assembly). The two forms of the END 
directive are 



label 
label 



END 
END 



expression 



where the label is again optional. If the first form is used, the 
assembly process stops, and the default starting address of the 
program is taken as 0000. Otherwise, the expression is evaluated, 
and becomes the program starting address (this starting address 
is included in the last record of the Intel formatted machine code 
"hex" file which results from the assembly). Thus, most CP/M 
assembly language programs end with the statement 

END 100H 

resulting in the default starting address of 100H (beginning of the 
transient program area). 

The EQU Directive 

The EQU (equate) statement is used to set up synonyms for 
particular numeric values. The form is 



label 



EQU 



expression 



where the label must be present, and must not label any other 
statement. The assembler evaluates the expression, and assigns 
this value to the identifier given in the label field. The identifier is 
usually a name which describes the value in a more human-oriented 
manner. Further, this name is used throughout the program to 
"parameterize" certain functions. Suppose for example, that data 
received from a Teletype appears on a particular input port, and 
data is sent to the Teletype through the next output port in 
sequence. 
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The series of equate statements could be used to define these 
ports for a particular hardware environment 



TTYBASE EQU 10H 
TTYIN EQU TTYBASE 

TTYOUT EQU TTYBASE + 1 



BASE PORT NUMBER FOR TTY 

TTYDATAIN 

TTY DATA OUT 



At a later point in the program, the statements which access the 
Teletype could appear as 

IN TTYIN ;READTTYDATATO REG-A 

OUT TTYOUT ;WRITE DATA TO TTY FROM REG-A 

making the program more readable than if the absolute I/O ports 
had been used. Further, if the hardware environment is redefined 
to start the Teletype communications ports at 7FH instead of 10H, 
the first statement need only be changed to 



TTYBASE EQU 7FH 



;BASE PORT NUMBER FOR TTY 



and the program can be reassembled without changing any other 
statement. 

The SET Directive 

The SET statement is similar to the EQU, taking the form 



label 



SET 



expression 



except that the label can occur on other SET statements within 
the program. The expression is evaluated and becomes the current 
value associated with the label. Thus, the EQU statement defines 



a label with a single value, while the SET statement defines a value 
which is valid from the current SET statement to the point where 
the label occurs on the next SET statement. The use of the SET is 
similar to the EQU statement, but is used most often in controlling 
conditional assembly. 

The IF and ENDIF Directives 

The IF and ENDIF statements define a range of assembly language 
statements which are to be included or excluded during the 
assembly process. The form is 

IF expression 
statement #1 
statement #2 

statement #n 
ENDIF 

Upon encountering the IF statement, the assembler evaluates 
the expression following the IF (all operands in the expression 
must be defined ahead of the IF statement). If the expression 
evaluates to a non-zero value, then statement #1 through statement 
#n are assembled; if the expression evaluates to zero, then the 
statements are listed but not assembled. Conditional assembly is 
often used to write a single "generic" program which includes a 
number of possible run-time environments, with only a few specific 
portions of the program selected for any particular assembly. The 
following program segments for example, might be part of a program 
which communicates with either a Teletype or a CRT console 
(but not both) by selecting a particular value for TTY before the 
assembly begins. 



130 CP/M Reference Manual 



TRUE 
FALSE 

TTY 



CONIN 
CONOUT 



CONIN 
CONOUT 



EQU 
EQU 

EQU 



TTYBASE EQU 
CRTBASE EQU 
IF 



EQU 
EQU 
ENDIF 



EQU 
EQU 
ENDIF 



OFFFFH 
NOT TRUE 

TRUE 

10H 
20H 
TTY 

TTYBASE 



;DEFINE VALUE OF TRUE 
;DEFINE VALUE OF FALSE 

;TRUEIFTTY, FALSE IF CRT 

;BASEOFTTY I/O PORTS 
;BASE OF CRT I/O PORTS 
;ASSEMBLE RELATIVE TO 
TTYBASE 
;CONSOLE INPUT 



TTYBASE+1 ;CONSOLE OUTPUT 



NOT TTY ;ASSEMBLE RELATIVE TO 

CRTBASE 
CRTBASE ;CONSOLE INPUT 

CRTBASE+1 ;CONSOLE OUTPUT 



IN CONIN 

OUT CONOUT 



;READ CONSOLE DATA 
;WRITE CONSOLE DATA 



In this case, the program would assemble for an environment 
where a Teletype is connected, based at port 10H. The statement 
defining TTY could be changed to 



TTY 



EQU 



FALSE 



and, in this case, the program would assemble for a CRT based at 
port20H. 
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The DB Directive 

The DB directive allows the programmer to define initialized 
storage areas in single precision (byte) format. The statement form 
is 



label 



DB 



e#1,e#2, ...,e#n 



where e#1 through e#n are either expressions which evaluate to 
8-bit values (the high order eight bits must be zero), or are ASCII 
strings of length no greater than 64 characters. There is no 
practical restriction on the number of expressions included on a 
single source line. The expressions are evaluated and placed 
sequentially into the machine code file following the last program 
address generated by the assembler. String characters are 
similarly placed into memory starting with the first character and 
ending with the last character. Strings of length greater than two 
characters cannot be used as operands in more complicated 
expressions (i.e., they must stand alone between the commas). 
Note that ASCII characters are always placed in memory with the 
parity bit reset (0). Further, recall that there is no translation from 
lower to upper case within strings. The optional label can be used 
to reference the data area throughout the remainder of the 
program. Examples of valid DB statements are 

data: DB 0,1,2,3,4,5 

DB data and 0ffh,5,377Q, 1+2+3+4 

signon: DB please type your name',cr,lf,0 

DB ABSHR8, C, DEAND7FH 

The DW Directive 

The DW statement is similar to the DB statement except double 
precision (two byte) words of storage are initialized. The form is 



label 



DW 



e#1,d#2 e#n 



where e#1 through e#n are expressions which evaluate to 16-bit 
results. Note that ASCII strings of length one or two characters are 
allowed, but strings longer than two characters disallowed. In all 
cases, the data storage is consistent with the 8080 processor: the 
least significant byte of the expression is stored first in memory, 
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followed by the most significant byte. Examples are 

doub: DW Offefh.doub t 4, signon$, 255+255 
DW a, 5, 'ab', 'CD', 6 shl 8 or 11b 

The DS Directive 

The DS statement is used to reserve an area of uninitialized 
memory, and takes the form 



label 



DS 



expression 



where the label is optional. The assembler begins subsequent 
code generation after the area reserved by the DS. Thus, the DS 
statement given above has exactly the same effect as the 
statement 

label: EQU $ ;LABEL VALUE IS CURRENT CODE LOCATION 
ORG $~ expression ;MOVE PAST RESERVED AREA 



Operation Codes 



Assembly language operation codes form the principal part of 
assembly language programs, and form the operation field of the 
instruction. In general, ASM accepts all the standard mnemonics 
for the Intel 8080 microcomputer, which are given in detail in the 
Intel manual 8080 Assembly Language Programming Manual. Labels 
are optional on each input line and, if included, take the value of 
the instruction address immediately before the instruction is issued. 
The individual operators are listed briefly in the following sections 
for completeness, although it is understood that the Intel manuals 
should be referenced for exact operator details. In each case, 

e3 represents a 3-bit value in the range of 0-7 which 

can be one of the predefined registers A, B, C, 
D, E, H, L, M, SP, or PSW. 

e8 represents an 8-bit value in the range 0-255 

e1 6 represents a 1 6-bit value in the range 0-65535 
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which can themselves be formed from an arbitrary combination 
of operands and operators. In some cases, the operands are 
restricted to particular values within the allowable range, such as 
the PUSH instruction. These cases will be noted as they are 
encountered. 

In the sections which follow, each operation code is listed in its 
most general form, along with a specific example, with a short 
explanation and special restrictions. 



Jumps, Calls and Returns 

The Jump, Call and Return instructions allow several different 
forms which test the condition flags set in the 8080 microcomputer 
CPU. The forms are 

Jump unconditionally to label 
Jump on non zero condition to label 
Jump on zero condition to label 
Jump no carry to label 
Jump on carry to label 
Jump on parity odd to label 
Jump on even parity to label 

GAMMA Jump on positive result to label 
Jump on minus to label 
Call subroutine unconditionally 
Call subroutine if non zero flag 
Call subroutine on zero flag 
Call subroutine if no carry set 
Call subroutine if carry set 
Call subroutine if parity odd 
Call subroutine if parity even 

GAMMA Call subroutine if positive result 



JMB 


e16 


JMP 


L1 


JNZ 


e16 


JMP 


L2 


JZ 


e16 


JMP 


100H 


JNC 


e16 


JNC 


L1+4 


JC 


e16 


JC 


L3 


JPO 


e16 


JPO 


$+8 


JPE 


e16 


JPE 


L4 


JP 


e16 


JP 


GAM! 


JM 


e16 


JM 


al 


CALL 


e16 


CALL 


S1 


CNZ 


e16 


CNZ 


S2 


CZ 


el 6 


CZ 


100H 


CNC 


e16 


CNC 


S1 4 4 


CC 


e16 


CC 


S3 


CPO 


e16 


CPO 


$4 8 


CPE 


e16 


CPE 


S4 


CP 


e16 


CP 


GAM! 
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CM e16 CM 
RST e3 RST 

RET 

RNZ 

RZ 

RNC 

RC 

RPO 

RPE 

RP 

RM 



b1 $c2 Call subroutine if minus flag 

Programmed "restart," equivalent to 

CALL 8*e3, except one byte call 

Return from subroutine 

Return if non zero flag set 

Return if zero flag set 

Return if no carry 

Return if carry flag set 

Return if parity is odd 

Return if parity is even 

Return if positive result 

Return if minus flag is set 



Immediate Operand Instructions 

Several instructions are available which load single or double 
precision registers, or single precision memory cells, with constant 
values, along with instructions which perform immediate arithmetic 
or logical operations on the accumulator (register A). 



MVI e3,e8 MVI B,255 



Move immediate data to 
register A, B, C, D, E, H, L, 
or M (memory) 



ADIe8 


ADI 


1 


Add immediate operand to A 
without carry 


ACIe8 


AC I 


OFFH 


Add immediate operand to A 
with carry 


SUIe8 


SUI 


L + 3 


Subtract from A without 
borrow (carry) 


SBIe8 


SBI 


LAND 11B 


Subtract from A with borrow 
(carry) 


ANI e8 


ANI 


$ AND7FH 


Logical "and" A with 



immediate data 
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XRI e8 



ORI e8 



CPIe8 



XRI 1111$0000B 



ORI LAND1 + 1 



CPI a' 



LXIe3,e16 LXI B,100H 



"Exclusive or" A with 
immediate data 

Logical "or" A with 
immediate data 

Compare A with immediate 
data (same as SUI except 
register A not changed) 

Load extended immediate to 
register pair (e3 must be 
equivalent to B, D, H, or SP) 



Increment and Decrement Instructions 

Instructions are provided in the 8080 repertoire for incrementing 
or decrementing single and double precision registers. The 
instructions are 



INR e3 INR E 



DCR e3 DCR A 



INX e3 INX SP 



DCX e3 DCX B 



OUT e8 OUT 255 



Single precision increment 
register (e3 produces one of 
A, B, C, D, E, H, L, M) 

Single precision decrement 
register (e3 produces one of 
A, B, C, D, E, H, L, M) 

Double precision increment 
register pair (e3 must be 
equivalent to B, D, H, or SP) 

Double precision decrement 
register pair (e3 must be 
equivalent to B, D, H, or SP) 

Send data from register A 
to port e8 
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Data Movement Instructions 

Instructions which move data from memory to the CPU and from 
CPU to memory are given below 



MOV e3,e3 MOV A,B 



LDAX e3 LDAX B 



STAX e3 STAX D 



LHLD e16 LHLD L1 



SHLD e16 SHLD L5+x 



LDA e16 LDA Gamma 



STA e16 STA X3-5 



POP e3 POP PSW 



PUSH e3 PUSH B 



IN e8 IN 



OUT e8 OUT 255 



Move data to leftmost 
element from rightmost 
element (e3 produces one of 
A, B,C, D, E, H, L, orM). 
MOV M,M is disallowed 

Load register A from 
computed address (e3 must 
produce either B or D) 

Store register A to computed 
address (e3 must produce 
either B or D) 

Load HL direct from 
location e16 (double 
precision load to H and L) 

Store HL direct to location 
e16 (double precision store 
from H and L to memory) 

Load register A from 
address e16 

Store register A into memory 
ate16 

Load register pair from 
stack, set SP (e3 must 
produce one of B, D, H, 
or PSW) 

Store register pair into stack, 
set SP (e3 must produce 
one of B, D, H, or PSW) 

Load register A with data 
from port e8 

Send data from register A 
to port e8 
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XTHL 
PCHL 
SPHL 
XCHG 



Exchange data from top of 
stack with HL 

Fill program counter with 
data from HL 

Fill stack pointer with data 
from HL 

Exchange DE pair with HL 
pair 



Arithmetic Logic Unit Operations 

Instructions which act upon the single precision accumulator to 
perform arithmetic and logic operations are 



ADD e3 ADD B 



ADC e3 ADC L 



SUB e3 SUB H 



SBB e3 SBB 2 



ANA e3 ANA 1-M 



XRA e3 XRA A 



ORA e3 ORA B 



CMP e3 CMP H 



Add register given by e3 to 
accumulator without carry 
(e3 must produce one of 
A, B, C, D, E, H.orL) 

Add register to A with carry, 
e3 as above 

Subtract reg e3 from A 
without carry, e3 is defined 
as above 

Subtract register e3 from A 
with carry, e3 defined 
as above 

Logical "and" reg with A, e3 
as above 

"Exclusive or" with A, e3 
as above 

Logical "or" with A, e3 
defined as above 

Compare register with A, e3 
as above 
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DAA 

CMA 

STC 

CMC 

RLC 

RRC 

RAL 

RAR 

DAD e3 DAD B 



Decimal adjust register A 
based upon last arithmetic 
logic unit operation 

Complement the bits in 
register A 

Set the carry flag to 1 

Complement the carry flag 

Rotate bits left, (re)set carry 
as a side effect (high order 
A bit becomes carry) 

Rotate bits right, (re)set 
carry as side effect (low 
order A bit becomes carry) 

Rotate carry /A register to 
left (carry is involved in 
the rotate) 

Rotate carry/A register to 
right (carry is involved in 
the rotate) 

Double precision add 
register pair e3 to HL(e3 
must produce B, D, H, or SP) 



Control Instructions 

The four remaining instructions are categorized as control 
instructions, and are listed below 

H LT Halt the 8080 processor 

Dl Disable the interrupt system 

El Enable the interrupt system 

NOP No operation 
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Error Messages 



When errors occur within the assembly language program, they 
are listed as single character flags in the leftmost position of the 
source listing. The line in error is also echoed at the console so 
that the source listing need not be examined to determine if errors 
are present. The error codes are 

D Data error: element in data statement cannot be 

placed in the specified data area 

E Expression error: expression is ill-formed and 

cannot be computed at assembly time 

L Label error: label cannot appear in this context 

(may be duplicate label) 

N Not implemented: features which will appear in 

future ASM versions (e.g., macros) are recognized, 
but flagged in this version 

O Overflow: expression is too complicated (i.e., too 

many pending operators) to compute; simplify it 

P Phase error: label does not have the same value 

on two subsequent passes through the program 

R Register error: the value specified as a register is 

not compatible with the operation code 

V Value error: operand encountered in expression is 

improperly formed 
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Several error messages are printed which are due to terminal 
error conditions 



NO SOURCE FILE 
PRESENT 

NO DIRECTORY SPACE 



SOURCE FILE NAME 
ERROR 

SOURCE FILE READ 
ERROR 



OUTPUT FILE WRITE 
ERROR 

CANNOT CLOSE FILE 



A Sample Session 



The file specified in the ASM 
command does not exist on 
disk 

The disk directory is full; erase 
files which are not needed, 
and retry 

Improperly formed ASM file 
name (e.g., it is specified with 
"?" fields) 

Source file cannot be read 
properly by the assembler, 
execute a TYPE to determine 
the point of error 

Output files cannot be written 
properly, most likely cause is 
a full disk; erase and retry 

Output file cannot be closed, 
check to see if disk is write 
protected 



The following session shows interaction with the assembler and 
debugger in the development of a simple assembly language 
program. 



ASM SORT Assemble SORT.ASM 

CP/M ASSEMBLER -VER 1 

01 5C next tree address 

003H USE FACTOR % of table used 00 to FF (hexadecimal) 

END OF ASSEMBLY 



SORT ASM source file 

SORT BAK backup from last edit 

SORT PRN print file (contains tab characters) 

SORT HEX machine code file 

A 'TYPE SORT PRN 

Source line 



machine code ; 

location 

0100 v ORG 

generated machine code 

LXI 
MVI 
LXI 
MVI 



SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 
START AT THE BEGINNING OF THE TRANSIENT PROGRAM AR 
100H 



0100 


214601 -J 


SORT 


0103 


3601 




0105 


214701 




0108 


3600 




01 OA 


7E 


; 

COMP: 


010B 


FE09 




010D 


D21901 




0110 


214601 


; 


0113 


7EB7C20001 




0118 


FF 


• truncated 



H.SW 
M. 1 
H, I 
M,0 



ADDRESS SWITCH TOGGLE 
SET TO 1 FOR FIRST ITERATION 
ADDRESS INDEX 
I =0 



COMPARE I WITH ARRAY SIZE 
MOV A, M ; A REGISTER = I 

CPI N-1 ;CYSETIFI (N-1) 

JNC CONT ; CONTINUE IF I = (N-2) 

END OF ONE PASS THROUGH DATA 

LXI H,SW ; CHECK FOR ZERO SWITCHES 

MOVA.M'ORA A' JNZ SORT; END OF SORT IFSW=0 



RST7 



; GO TO THE DEBUGGER INSTEAD OF RE 



C\ 



0119 5F16002148CONT: 
0121 4E792346 



0125 23 

0126 965778239E 
012B DA3F01 



01 2E B2CA3F01 
0132 56702B5E 
0136 712B722B73 



013B 21460134 

013F 21470134C3INCI: 

0146 00 SW: 

0147 I: 

0148 050064001 EAV: 
000A = N 

01 5C y ^- equate value 



CONTINUE THIS PASS 

ADDRESSING I, SO LOAD AV(I) INTO REGISTERS 

MOV E.A 1 MVI D.O! LXI H.AV! DAD D! DAD D 

MOV CM' MOV A,C! INX H! MOV B M 

LOW ORDER BYTE IN A AND C. HIGH ORDER BYTE IN B 



MOV H AND L TO ADDRESS AV(I 
INX H 



1) 



COMPARE VALUE WITH REGS CONTAINING AV(I) 

SUB M! MOV D.A! MOV A.B! INX H! SBB M : SUBTRACT 

BORROWSETIF AV(I + 1) AV(I) 

JC INCI : SKIP IF IN PROPER ORDER 

CHECK FOR EQUAL VALUES 

ORAD' JZ INCI ; SKIP IF AV( I) = AV(I + 1) 

MOV D.M! MOV M,B! DCX H! MOV E.M 

MOV M.C! DCX H! MOV M.D! DCX H! MOV M.E 

INCREMENT SWITCH COUNT 
LXI H.SW! INR M 

INCREMENT I 

LXI H.IIINR M! JMPCOMP 

DATA DEFINITION SECTION 

DB ; RESERVE SPACE FOR SWITCH COUNT 

DS 1 ; SPACE FOR INDEX 

DW 5,100.30,50,20.7,1000,300,100,-32767 

EQU |$-AV)/2 ; COMPUTE N INSTEAD OF PRE 

END 



DIRSORT* 
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A TYPE SORTHEX 



10010000214601360121470136007EFE09D2190140 

1001 1000214601 7EB7C20001FF5F1600214801 1983 

10012000194E79234623965778239EDA3F01B2CAA7( 

100130003F0156702B5E712B722B732146013421C7 

0701 40004701 34C30A01 006E 

1 001 4800050064001 E0032001 4000700E8032C01 BB 

:0401580064000180BE 

:0000000000 

A: DDT SORTHEX start debug run 



machine code 
in HEX format 



16KDDTVER 10 

NEXT PC 

81 5C 0000 default address (no address on END statement} 

-XP 

P=0000 100 change PC to 100 



— UFFFF untrace for 65535 steps 












abort with 




















(~ rubout 


C0Z0M0E0I0 


A=00 


B=0000 


D=0000 


H = 


=0000 


S=0100 


P=0100 


LXI 


H,0146*0100 


— T1 trace 10, 6 steps 
















COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0100 


LXI 


1-1,0146 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0103 


MVI 


M.01 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0105 


LXI 


1-1,0147 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=0108 


MVI 


M.00 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=010A 


MOV 


A,M 


COZOMOEOIO 


A=00 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=010B 


CPI 


09 


C1Z0M1E0I0 


A=00 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=010D 


JNC 


0119 


C1Z0M1E0I0 


A=00 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=0110 


LXI 


1-1,0146 


C1Z0M1E0I0 


A=00 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0113 


MOV 


A,M 


C1Z0M1E0I0 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0114 


ORA 


A 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0115 


JNZ 


0100 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0100 


LXI 


1-1,0146 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0103 


MVI 


M.01 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0146 


S=0100 


P=0105 


LXI 


1-1,0147 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=0108 


MVI 


M,00 


COZOMOEOIO 


A=01 


B=0000 


D=0000 


H = 


=0147 


S=0100 


P=010A 


MOV 


A,M*010B 


-A10D 


































stopped at -~^~~ 




010D JC 


1 1 9 change to a jump on carry 






10BH 






0110 





















-XP 



P=010B 100 reset program counter back to beginning of program 



-T10 trace execution fori OH steps 



COZOMOEOIO 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


S=0100 


P=0100 


LXI 


H,0146 


COZOMOEOIO 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0146 


S=0100 


P=0103 


MVI 


M.01 


COZOMOEOIO 


A= 


=00 


B = 


=0000 


D = 


=0000 


H = 


=0146 


S=0100 


P=0105 


LXI 


H,0147 


COZOMOEOIO 


A= 


=00 


B = 


=0000 


D = 


=0000 


H = 


=0147 


S = 0100 


P=0108 


MVI 


M,00 ,, 
alt 


COZOMOEOIO 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


s=oioo 


P=010A 


MOV 


A,M / 


COZOMOEOIO 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


S=0100 


P=010B 


CPI 


09 / 


C1Z0M1E0I0 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


s=oioo 


P=010D 


JC 


0119 


C1Z0M-1E0I0 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


s=oioo 


P=0119 


MOV 


E,A 


C1Z0M1E0I0 


A= 


=00 


B = 


=0000 


D= 


=0000 


H = 


=0147 


S=0100 


P=011A 


MVI 


D,00 


C1Z0M1E0I0 


A= 


=00 


B = 


=0000 


D= 


=0000 


H' 


=0147 


S=0100 


P=011C 


LXI 


H.0148 


C1Z0M1E0I0 


A= 


=00 


B- 


=0000 


D= 


=0000 


H 


=0148 


S=0100 


P=011F 


DAD 


D 


C0ZOM1E0IO 


A= 


= 00 


B = 


=0000 


D= 


=0000 


H- 


=0148 


s=oioo 


P=0120 


DAD 


D 


C0ZOM1E0IO 


A= 


=00 


B = 


=0000 


D = 


=0000 


H 


= 0148 


S=0100 


P=0121 


MOV 


CM 


C0ZOM1E0IO 


A= 


=00 


B" 


=0005 


D = 


=0000 


H 


=0148 


S=0100 


P=0122 


MOV 


A.C 


C0ZOM1E0IO 


A= 


=05 


B- 


=0005 


D = 


=0000 


H 


=0148 


s=oioo 


P=0123 


INX 


H 


C0ZOM1E0IO 


A= 


=05 


B = 


=0005 


D = 


=0000 


H 


=0149 


S=0100 


P=0124 


MOV 


B,M»0125 






















Automatic 
























breakpoint 





/ altered instruction 
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-L100 



0100 


LXI 


H.0146 \ 




0103 


MVI 


M.01 1 




0105 


LXI 


H.0147 / 




0108 
01 OA 


MVI 
MOV 


M,00 / 
A.M \ 


list some code 


010B 


CPI 


09 / 


from 100H 


010D 


JC 


0119 I 




0110 


LXI 


H.0146 \ 




0113 


MOV 


A,M 




0114 


ORA 


A / 




0115 

-L 


JNZ 


0100 




0118 
0119 


RST 
MOV 


07 \ 
E,A / 


list more 


011A 


MVI 


D,00 > 




011C 


LXI 


H.0148 I 




— abort list with rubout I 





-G,1 18 start program from current PC (0125H) and run in real time to11BH 

01 27 stopped with an external interrupt 7 from front panel (program was looping indefinitely) 

-T4 

look at looping program in trade modes 

A=38 B=0064 D=0006 H=0156 S=0100 P=0127 MOV D,A 

A=38 B=0064 D=3806 H=0156 S=0100 P=0128 MOV A,B 

A=00 B=0064 D=3806 H=0156 S=0100 P=0129 INX H 

A=00 B=0064 D=3806 H=0157 S=0100 P=012A SBB M«012B 



COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
-D148 



,data is sorted, but program doesn't stop 



03 01 80 00 00 
00 00 00 00 00 



00 00 
00 00 



2 D.D 



-GO return to CP/M 

DDT SORT.HEX reload the memory image 

16KDDTVER 1.0 
NEXT PC 
01 5C 0000 
-XP 



P=0000 1 00 Set PC to beginning of program 
— L10D list bad opcode 



010D JNC 0119 

0110 LXI H,0146 

— abort list with rubout 



-A10D 


assemble new opcode 


010D 


JC 119 


0110 




-L100 


list starting section of program 


0100 


LXI H,0146 


0103 


MVI M.01 


0105 


LXI H,0147 


0108 


MVI M,00 



— abort list with rubout 

— A1 03 change "switch " initialization to 00 

0103 MVI M,0 

0105 

- " C return to CP/M with ctl-c IGO works as well) 
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SAVE 1 S0RT.COM save 1 page 1256 bytes, from 100H to 1FFMH) on disk incase 

we have to reload later 
A DDT S0RT.COM restart DDT with 

saved memory image 
16K DDT VER 1.0 
NEXT PC 

0200 0100 VOM "file always starts with address WOH 
— G run the program from PC- 100H 



*01 1 8 programmed stop IHST 71 encountered 
-D148 



- data properly sorted 



0148 05 00 07 00 14 00 1E 00 

0150 32 00 64 00 64 00 2C 01 E8 03 01 80 00 00 00 00 2 D D 

0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

0170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 



- GO return to CP/M 

ED SORT. ASM make changes to original program 

ctl-Z 
*N,0"ZOTT find next ".0" 

MVI M,0 

* — up one line in text 

LXI H.I 

*— up another line 

MVI M.1 

*KT kill line and type next line 

LXI H.I 

*l insert new line 

MVI M.O 



H.I 



;CONTINUE IF I = (N-2) 
CONT ; CONTINUE IF I 



LXI 
*NJNC"ZOT 

JNC*T 
CONT 
*-2DIC"Z0LT 
JC 
*E ^ source from disk A 

{ s^hex to disk A 
ASM SORT.AAZ^ skip pm tile 

CP/M ASSEMBLER - VER 1.0 

01 5C next address to assemble 
003H USE FACTOR 
END OF ASSEMBLY 

DDT SORT.HEX test program changes 

16K DDT VER 1.0 

NEXT PC 

01 5C 0000 

-G100 



I = 

ADDRESS INDEX 

SET TO 1 FOR FIRST ITERATION 

ADDRESS INDEX 

ZEROSW 

ADDRESS INDEX 



= (N-2) 



*0118 
-D148 



- data sorted 



0148 B5 00 07 00 14 00 1E 00 

0150 32 00 64 00 64 00 2C 01 E8 03 01 80 00 00 00 00 2 D D 
0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 

— abort with rubout 

— GO return to CP/M — program checks OK. 
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CP/M Dynamic Debugging Tool 



Introduction 



The DDT program allows dynamic interactive testing and debugging 
of programs generated in the CP/M environment. The debugger 
is initiated by typing one of the following commands at the CP/M 
Console Command level 



DDT 

DDTfilename.HEX 

DDTfilename.COM 



where "filename" is the name of the program to be loaded and 
tested. In both cases, the DDT program is brought into main 
memory in the place of the Console Command Processor (refer 
to the CP/M Interface Guide for standard memory organization), 
and thus resides directly below the Basic Disk Operating System 
portion of CP/M. The BDOS starting address, which is located in 
the address field of the JMP instruction at location 5H, is altered 
to reflect the reduced Transient Program Area size. 

The second and third forms of the DDT command shown above 
perform the same actions as the first, except there is a subsequent 
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automatic load of the specified HEX or COM file. The action is 
identical to the sequence of commands 

DDT 

Ifilename.HEX or lfilename.COM 

R 

where the I and R commands set up and read the specified 
program to test. (See the explanation of the I and R commands 
below for exact details.) 

Upon initiation, DDT prints a sign-on message in the format 

DDTVERm.m 

where 



D 



O 
S 



Digital Research standard version 

MDS version 

IMSAI standard version 

Omron systems 

Digital Systems standard version 



m.m is the revision number. 

Following the sign on message, DDT prompts the operator with the 
character "-" and waits for input commands from the console. 
The operator can type any of several single characters commands, 
terminated by a carriage return to execute the command. Each 
line of input can be line-edited using the standard CP/M controls 



rubout remove the last character typed 

Control-X remove the entire line, ready for re-typing 

Control-C system reboot 

Any command can be up to 32 characters in length (an automatic 
carriage return is inserted as the 33rd character), where the first 
character determines the command type. 
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D 

F 

G 

I 

L 

M 

R 
S 
T 
U 
X 



enter assembly language mnemonics with 
operands 

display memory in hexadecimal and ASCII 

fill memory with constant data 

begin execution with optional breakpoints 

set up a standard input file control block 

list memory using assembler mnemonics 

move a memory segment from source to 
destination 

read program for the subsequent testing 

substitute memory values 

trace program execution 

untraced program monitoring 

examine and optionally alter the CPU state 



The command character, in some cases, is followed by zero, one, 
two, or three hexadecimal values which are separated by commas 
or single blank characters. All DDT numeric output is in hexadecimal 
form. In all cases, the commands are not executed until the 
carriage return is typed at the end of the command. 

At any point in the debug run, the operator can stop execution of 
DDT using either a Control-C or GO (jump to location 0000H), and 
save the current memory image using a SAVE command of the 
form 

SAVE nfilename.COM 

where n is the number of pages (256 byte blocks) to be saved on 
disk. The number of blocks can be determined by taking the high 
order byte of the top load address and converting this number to 
decimal. For example, if the highest address in the Transient 
Program Area is 1234H then the number of pages is 12H, or 18 
in decimal. Thus the operator could type a Control-C during the 
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debug run, returning to the Console Processor level, followed by 

SAVE 18X.COM 

The memory image is saved as X.COM on the diskette, and can 
be directly executed by simply typing the name X. If further testing 
is required, the memory image can be recalled by typing 

DDTX.COM 

which reloads the previously saved program from location 100H 
through page 18 (12FFH). The machine state is not a part of the 
COM file, and thus the program must be restarted from the 
beginning in order to properly test it. 



DDT Commands 



The individual commands are given below in some detail. In 
each case, the operator must wait for the prompt character (-) 
before entering the command. In the explanation of each command, 
the command letter is shown in some cases with numbers 
separated by commas, where the numbers are represented by 
lower case letters. These numbers are always assumed to be in a 
hexadecimal radix, and from one to four digits in length (longer 
numbers will be automatically truncated on the right). 

Many of the commands operate upon a "CPU state" which 
corresponds to the program under test. The CPU state holds the 
registers of the program being debugged, and initially contains 
zeroes for all registers and flags except for the program counter (P) 
and stack pointer (S), which default to 100H. The program 
counter is subsequently set to the starting address given in the last 
record of a HEX file if a file of this form is loaded (see the I and R 
commands). 
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The A (Assemble) Command 



DDT allows inline assembly language to be inserted into the current 
memory image using the A command which takes the form 

As 

where s is the hexadecimal starting address for the inline 
assembly. DDT prompts the console with the address of the next 
instruction to fill, and reads the console, looking for assembly 
language mnemonics (see the Intel 8080 Assembly Language 
Reference Card for a list of mnemonics), followed by register 
references and operands in absolute hexadecimal form. Each 
successive load address is printed before reading the console. 
The A command terminates when the first empty line is input from 
the console. 

Upon completion of assembly language input, the operator can 
review the memory segment using the DDT disassembler. (See the 
L command.) 

Note that the assembler/disassembler portion of DDT can be 
overlayed by the transient program being tested, in which case the 
DDT program responds with an error condition when the A and L 
commands are used. 



The D (Display) Command 



The D command allows the operator to view the contents of 
memory in hexadecimal and ASCII formats. The forms are 



D 

Ds 

Ds,f 



In the first case, memory is displayed from the current display 
address (initially 100H), and continues for 16 display lines. Each 
display line takes the form shown below 

aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 
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where aaaa is the display address in hexadecimal, and bb represents 
data present in memory starting at aaaa. The ASCII characters 
starting at aaaa are given to the right (represented by the sequence 
of c's), where non-graphic characters are printed as a period (.) 
symbol. Note that both upper and lower case alphabetics are 
displayed, and thus will appear as upper case symbols on a 
console device that supports only upper case. Each display line 
gives the values of 16 bytes of data, except that the first line 
displayed is truncated so that the next line begins at an address 
which is the multiple of 16. 

The second form of the D command shown above is similar to 
the first, except that the display address is first set to address s. 
The third form causes the display to continue from address s 
through address f. In all cases, the display address is set to the first 
address not displayed in this command, so that a continuing 
display can be accomplished by issuing successive D commands 
with no explicit addresses. 

Excessively long displays can be aborted by pushing the rubout 
key. 



The F(Fill) Command 



The F command takes the form 
Fs.f.c 



where s is the starting address, f is the final address, and c is a 
hexadecimal byte constant. The effect is as follows: DDT stores the 
constant c at address s, increments the value of s and tests 
against f. If s exceeds f then the operation terminates, otherwise 
the operation is repeated. Thus, the fill command can be used to 
set a memory block to a specific constant value. 
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The G (Go) Command 



Program execution is started using the G command, with up to two 
optional breakpoint addresses. The G command takes one of the 
forms 

G 

Gs 

Gs,b 

Gs,b,c 

G,b 

G,b,c 

The first form starts execution of the program under test at the 
current value of the program counter in the current machine 
state, with no breakpoints set. The current program counter can be 
viewed by typing an X or XP command. The second form is 
similar to the first except that the program counter in the current 
machine state is set to address s before execution begins. The 
third form is the same as the second, except that program execution 
stops when address b is encountered (b must be in the area of 
the program under test). The instruction at location b is not executed 
when the breakpoint is encountered. The fourth form is identical 
to the third, except that two breakpoints are specified, one at b and 
the other at c. Encountering either breakpoint causes execution 
to stop, and both breakpoints are subsequently cleared. The last 
two forms take the program counter from the current machine 
state, and set one and two breakpoints, respectively. 

Execution continues from the starting address in real-time to the 
next breakpoint. That is, there is no intervention between the 
starting address and the break address by DDT. Thus, if the program 
under test does not reach a breakpoint, control cannot return to 
DDT. Upon encountering a breakpoint, DDT stops execution and 
types 



where d is the stop address. The machine state can be examined 
at this point using the X (Examine) command. The operator must 
specify breakpoints which differ from the program counter address 
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at the beginning of the G command. Thus, if the current program 
counter is 1234H, then the commands 



and 



G,1234 
G400,400 



both produce an immediate breakpoint, without executing any 
instructions whatsoever. 



The I (Input) Command 



The I command allows the operator to insert a file name into the 
default file control block at 5CH (the file control block created by 
CP/M for transient programs is placed at this location; see the 
CP/M Interface Guide). The default FCB can be used by the 
program under test as if it had been passed by the CP/M Console 
Processor. Note that this file name is also used by DDT for 
reading additional HEX and COM files. The form of the I command is 



or 



Ifilename 



Ifilename.filetype 



If the second form is used, and the filetype is either HEX or 
COM, then subsequent R commands can be used to read the pure 
binary or hex format machine code (see the R command for 
further details). 

The L (List) Command 

The L command is used to list assembly language mnemonics in a 
particular program region. The forms are 

L 

Ls 

Ls,f 
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The first command lists twelve lines of disassembled machine 
code from the current list address. The second form sets the list 
address to s, and then lists twelve lines of code. The last form 
lists disassembled code from s through address f. In all three cases, 
the list address is set to the next unlisted location in preparation 
for a subsequent L command. Upon encountering an execution 
breakpoint, the list address is set to the current value of the 
program confer (see the G and T commands). Again, long typeouts 
can be aborted using the rubout key during the list process. 



The M (Move) Command 



The M command allows block movement of program or data 
areas from one location to another in memory. The form is 

Ms,f,d 

where s is the start address of the move, f is the final address of the 
move, and d is the destination address. Data is first moved from s 
to d, and both addresses are incremented. If s exceeds f then the 
move operation stops, otherwise the move operation is repeated. 



The R (Read) Command 



The R command is used in conjunction with the I command to 
read COM and HEX files from the diskette into the transient 
program area in preparation for the debut run. The forms are 

R 
Rb 



where b is an optional bias address which is added to each program 
or data address as it is loaded. The load operation must not 
overwrite any of the system parameters from 000H through OFFH 
(i.e., the first page of memory). If b is omitted, then b = 0000 is 
assumed. The R command requires a previous I command, 
specifying the name of a HEX or COM file. The load address for 
each record is obtained from each individual HEX record, while 



CP/M Dynamic Debugging Tool 



an assumed load address of 100H is taken for COM files. Note that 
any number of R commands can be issued following the I 
command to re-read the program under test, assuming the tested 
program does not destroy the default area at 5CH. Further, any 
file specified with the filetype "COM" is assumed to contain machine 
code in pure binary form (created with the LOAD or SAVE 
command), and all others are assumed to contain machine code in 
Intel hex format (produced, for example), with the ASM command). 

Recall that the command 

DDT filename. filetype 

which initiates the DDT program is equivalent to the commands 

DDT 

-Ifilename. filetype 

-R 

Whenever the R command is issued, DDT responds with either the 
error indicator "?" (file cannot be opened, or a checksum error 
occurred in a HEX file), or with a load message taking the form 

NEXT PC 
nnnn pppp 

where nnnn is the next address following the loaded program, 
and pppp is the assumed program counter (100H for COM files, or 
taken from the last record if a HEX file is specified). 



The S (Set) Command 



The S command allows memory locations to be examined and 
optionally altered. The form of the command is 



Ss 

where s is the hexadecimal starting address for examination and 
alteration of memory. DDT responds with a numeric prompt, 
giving the memory location, along with the data currently held in 
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the memory location. If the operator types a carriage return, then 
the data is not altered. If a byte value is typed, then the value is 
stored at the prompted address. In either Gase, DDT continues to 
prompt with successive addresses and values until either a period 
(.) is typed by the operator, or an invalid input value is detected. 



The T (Trace) Command 



The T command allows selective tracing of program execution 
for 1 to 65535 program steps. The forms are 

T 
Tn 

In the first case, the CPU state is displayed, and the next 
program step is executed. The program terminates immediately, 
with the termination address displayed as 

*hhhh 



where hhhh is the next address to execute. The display address 
(used in the D command) is set to the value of H and L, and the list 
address (used in the L command) is set to hhhh. The CPU state 
at program termination can then be examined using the X command. 

The second form of the T command is similar to the first, except 
that execution is traced for n steps (n is a hexadecimal value) 
before a program breakpoint occurs. A breakpoint can be forced in 
the trace mode by typing a rubout character. The CPU state is 
displayed before each program step is taken in trace mode. The 
format of the display is the same as described in the X command. 

Note that program tracing is discontinued at the interface to 
CP/M, and resumes after return from CP/M to the program under 
test. Thus, CP/M functions which access I/O devices, such as 
the diskette drive, run in real-time, avoiding I/O timing problems. 
Programs running in trace mode execute approximately 500 
times slower than real time since DDT gets control after each user 
instruction is executed. Interrupt processing routines can be 
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traced, but it must be noted that commands which use the breakpoint 
facility (G, T, and U) accomplish the break using a RST 7 instruction, 
which means that the tested program cannot use this interrupt 
location. Further, the trace mode always runs the tested program 
which interrupts enabled, which may cause problems if 
asynchronous interrupts are received during tracing. 

Note also that the operator should use the rubout key to get control 
back to DDT during trace, in order to ensure that the trace for the 
current instrucion is completed before interruption. 



The U (Untrace) Command 



The U command is identical to the T command except that 
intermediate program steps are not displayed. The untrace mode 
allows from 1 to 65535 (OFFFFH) steps to be executed in 
monitored mode, and is used principally to retain control of an 
executing program while it reaches steady state conditions. All 
conditions of the T command apply to the U command. 



The X (Examine) Command 

The X command allows selective display and alteration of the 
current CPU state for the program under test. The forms are 



X 
Xr 



where r is one of the 8080 CPU registers 

C Carry Flag 

Z Zero Flag 

M Minus Flag 

E Even Parity Flag 

I Interdigit Carry 

A Accumulator 

B BC register pair 

D DE register pair 



(0/1) 

(0/1) 

(0/1) 

(0/1) 

(0/1) 

(0-FF) 

(0-FFFF) 

(0-FFFF) 
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H 


HL register pair 


(O-FFFF 


S 


Stack Pointer 


(O-FFFF 


P 


Program Counter 


(O-FFFF 



In the first case, the CPU register state is displayed in the format 

CfZfMfEflf A=bb B=dddd D=dddd H-dddd S=dddd P=dddd inst 

where f is a or 1 flag value, bb is a byte value, and dddd is a 
double byte quantity corresponding to the register pair. The "inst" 
field contains the disassembled instruction which occurs at the 
location addressed by the CPU state's program counter. 

The second form allows display and optional alteration of register 
values, where r is one of the registers given above (C, Z, M, E, I, 
A, B, D, H, S, or P). In each case, the flag or register value is the 
first displayed at the console. The DDT program then accepts 
input from the console. If a carriage return is typed, then the flag or 
register value is not altered. If a value in the proper range is 
typed, then the flag or register value is altered. Note that BC, DE, 
and HL are displayed as register pairs. Thus, the operator types 
the entire register pair when B, C, or the BC pair is altered. 



Implementation Notes 



The organization of DDT allows certan non-essential portions to be 
overlayed in order to gain a larger transient program area for 
debugging large programs. The DDT program consists of two parts: 
the DDT nucleus and the assembler/disassembler module. The 
DDT nucleus is loaded over the Console Command Processor, and, 
although loaded with the DDT nucleus, the assembler/disassembler 
is overlayable unless used to assemble or disassemble. 

In particular, the BDOS address at location 6H (address field of 
the JMP instruction at location 5H) is modified by DDT to address 
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the base location of the DDT nucleus which, in turn, contains a 
JMP instruction to the BDOS. Thus, programs which use this address 
field to size memory see the logical end of memory at the base 
of the DDT nucleus rather than the base of the BDOS. 

The assembler/disassembler module resides directly below the 
DDT nucleus in the transient program area. If the A, L, T, or X 
commands are used during the debugging process then the DDT 
program again alters the address field at 6H to include this 
module, thus further reducing the logical end of memory. If a 
program loads beyond the beginning of the assembler/disassembler 
module, the A and L commands are lost (their use produces a "?" 
in response), and the trace and display (T and X) commands list the 
"inst" field of the display in hexadecimal, rather than as a decoded 
instruction. 



Sample Session 



The following example shows an edit, assemble, and debug for a 
simple program which reads a set of data values and determines 
the largest value in the set. The largest value is taken from the 
vector, and stored into "LARGE" at the termination of the program. 



ED SCAN ASM 



tab character ..rubout mbout gch0 

L-L^ARTOFTRANSLENTAREA 
JJENGJH OF VECJORTO SCAN 
' LARGER-R_ST VALUE SO FAR 
H.VECT. i_BA_SE OFJ/ECTOR 
; GET WLU E 
J LARGER VALUE IN CJ 
JUMP IF LARGERVALUE NOT FOUND 



" - I ORG " - I 100H 
MVI B.LEN 

MVI CO 

L OOP POOL LXI 

LOOP; 4 MOV AM 

rubout' 1 SUB C 

deletes' JNC NFOUND , ^^, I1 ^.._- L ^ ■- 

.characters NEW LARGESTVALU E ,_STOR E JT TO C 
MOV '" C,A 



NFOUND: 



[NX 
DCR 
JNZ 



H 



LOOP 



TO NEXT ELEMENT 
MORE TO SCAN' 
FOR ANOTHER 



END OF SCAN. STORE C 

MOV~~ A£ ; GET LARGEST VALUE 

STA LARGE 

JMP ; REBOOT 



Create Source 
Program - underlined 
characters typed 
by programmer. 
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TEST DATA 




VECT: 


DB 


2,0,4,3,5.6,1,5 


LEN 


EQU 


$-VECT 


LENGTH 


LARGE: 


DS 


1 


LARGEST VALUE ON EXIT 




END 






TZ'BOP 










ORG 


100H 


START OF TRANSIENT AREA 




MVI 


B.LEN 


LENGTH OF VECTOR TO SCAN 




MVI 


CO 


LARGEST VALUE SO FAR 




LXI 


H.VECT 


BASE OF VECTOR 


LOOP: 


MOV 


A,M 


GET VALUE 




SUB 


C 


LARGER VALUE INC? 




JNC 


NFOUND 


JUMP IF LARGER VALUE NOT FOUND 




NEW LARGEST VALUE, 


STORE ITTOC 




MOV 


C.A 




NFOUND 


INX 


H 


TO NEXT ELEMENT 




DCR 


B 


MORE TO SCAN? 




JN2 


LOOP 


FOR ANOTHER 




END OF SCAN, STORE C 






MOV 


A,C 


GET LARGEST VALUE 




STA 


' LARGE 






JMP 





REBOOT 




TEST DATA 




VECT: 


DB 


2,0,4,3,5,6,1, 


5 


LEN 


EQU 


$-VECT 


LENGTH 


LARGE: 


DS 
END 


1 


LARGEST VALUE ON EXIT 


'_E 


- 


End of Edit 




ASM SCAN 


o*~. 







Start Assembler 
CP/M ASSEMBLER - VER 1 .0 



0122 

002H USE FACTOR 






END OF ASSEMBLY Assembly Complete - Look at Program Listing 


TYPE SCAN , PRN 






Code Address/ 


Source Program 




0100 


Machine Code > 


ORG 100H 


START OF TRANSIENT AREA 


0100 


0608 ^___^ 


V MVI B.LEN 


LENGTH OF VECTOR TO SCAN 


0102 


OEOC 


MVI CO 


LARGEST VALUE SO FAR 


0104 


211901 


LXI H, VECT. 


BASE OF VECTOR 


0107 


7E LOOP: 


MOV A.M 


GET VALUE 


0108 


91 


SUB C 


LARGER VALUE IN C? 


0109 


D20D01 


JNC NFOUND 


JUMP IF LARGER VALUE NOT FOUND 






NEW LARGEST VALUE, 


STORE ITTOC 


01 OC 


4F 


MOV C.A 




010D 


23 NFOUND 


INX H 


TO NEXT ELEMENT 


010E 


05 


DCR B 


MORE TO SCAN? 


010F 


C20701 


JNZ LOOP 

END OF SCAN. STORE C 


FOR ANOTHER 


0112 


79 


MOV A,C 


GET LARGEST VALUE 


0113 


322101 


STA LARGE 




0116 


C30000 


JMP 


REBOOT 


Code/data listing ; 






truncated — ^ ; 


TEST DATA 





0119 0200040305VECT: DB 

0008 = ~x LEN EQU 

0121 Value of) LARGE: DS 

0122 Equate END 



2.0,4,3,5,6,1,5 

S-VECT : LENGTH 

1 ; LARGEST VALUE ON EXIT 
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DDT SCAN HEX 

16K DDT VER 1.0 
NEXT PC 
0121 0000 
-X *• 



Start Debugger using hex format machine code 



last load address + 1 next instruction 

i to execute at 

C0Z0M0E0I0 A=00 B=0000 D=0000 H=0000 S=0100 P=0000 OUT 7F PC=0 
-XP i 



P=0000 100 
-X 



^- Examine registers oefore debug run 
Change PC to 100 
Look at registers again 



-L100 



r~ PC changed 
COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MVI B,08^ 

Next instruction 
to execute at PC= 100 



Disassembled Machine 
Code at 100H 
(See Source Listing 
tor comparison) 



0100 


MVI 


B,08 


0102 


MVI 


COO 


0104 


LXI 


H.0119 


0107 


MOV 


A.M 


0108 


SUB 


C 


0109 


JNC 


010D 


010C 


MOV 


C,A 


010D 


INX 


H 


010E 


DCR 


B 


010F 


JNZ 


0107 


0112 
-L 


MOV 


A.C 


0113 


STA 


0121 


0116 


JMP 


0000 


0119 


STAX 


B 


011A 


NOP 




011B 


INR 


B 


011C 


INX 


B 


011D 


DCR 


B 


01 1E 


MVI 


B.01 


0120 


DCR 


B 


0121 


LXI 


D.2200 


0124 


LXI 


H.0200 



A little more 
machine code 
(note that Program 
ends at location 116 
with a JMP to 0000) 



-A1J6 enter inline assembly mode to change the JMP to 0000 into a RST 7, which 
will cause the program under test to return to DDT if 1 16H 

0116 RST 7 is ever executed. 

01 1 7 (single carriage return stops assembly mode) 

-L_m List Code at 113H to check that RST 7 was properly inserted 
in place o( JMP 



0113 


STA 


0121 


0116 


RST 


07 — 


0117 


NOP 




0118 


NOP 




0119 


STAX 


B 


011A 


NOP 




011B 


INR 


B 


011C 


INX 


B 
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H=0000 S=0100 P=0100 MVI B,08 
initial CPU state, before \ is executed 
H=0000 S=0100 P=0100 MVI B,08«0102 

automatic breakpoint ^ 
H=0000 S=0100 P=0102 MVI C,00*0104 



— X Look at registers 

COZOMOEOIO A=00 B=0000 D=0000 
— T Execute Program for one step. 

COZOMOEOIO A=00 B=0000 D=0000 
— I Trace one step again (note 08H in B) 

COZOMOEOIO A=00 B=0000 D=OO0O 
— T Trace again (Register C is cleared) 

COZOMOEOIO A=00 B=0800 D=0000 H=0000 S=O100 P=0104 LXIH,01 19*0107 
— 13 Trace three steps 

COZOMOEOIO A=00 B=0800 D=0000 H=0119 S = 
COZOMOEOIO A=02 B=0800 D=0000 H=0119 S = 
C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S = 

— D119 Display memory starting at 11 9H 

Program data 

0119 /02 00 04 03 05 06 Op 

0120 KQ§STl 00 22 21 00 02 7E EB 77 13 
0130 C2 27 01 C3 03 29 00 00 00 00 00 
0140 00 00 00 00 00 00 00 00 00 00 00 
0150 00 00 00 00 00 00 00 00 00 00 00 
0160 00 00 00 00 00 00 00 00 00 00 00 
0170 00 00 00 00 00 00 00 00 00 00 00 
0180 00 00 00 00 00 00 00 00 00 00 00 
0190 00 00 00 00 00 00 00 00 00 00 00 
01 AO 00 00 00 00 00 00 00 00 00 00 00 
01 BO 00 00 00 00 00 00 00 00 00 00 00 
01C0 00 00 00 00 00 00 00 00 00 00 00 



0100 P 


=0107 


MOV 


A,M 


0100 P 


=0108 


SUB 


c 


0100 P 


=0109 


JNC 


010D*010D 


Automatic breakpoint at 10DH -J 










-rLower case x^ 


23 EB 


OB 


@- 


*"bT 


...'■/..". w.$.Q) 


00 00 


00 


sa 


00 




00 00 


00 


00 


00 




00 00 


00 


00 


00 


Data is displayed 


00 00 


00 


00 


00 


in ASCII with a ,, 0" 


00 00 


00 


00 


00 


in the position of 


00 00 


00 


00 


00 


non-graphic 


00 00 


00 


00 


00 


characters 


00 00 


00 


00 


00 




00 00 


00 


00 


00 




00 00 


00 


00 


00 





Current CPU state 



^ 



P=010E 


DCR 


B 


Automatic 


P=010F 


JNZ 


0107 


Breakpoint 


P=0107 


MOV 


A.M 




P=0108 


SUB 


C«0109 





C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S=0100 P=010D INX H 
—15 Trace 5 steps from current CPU state 

C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S=0100 P=010D INX H 

C0Z0M0E0I1 A=02 B=0800 D=0000 H=011A S=0100 

C0Z0M0E0I1 A=02 B=0700 D=0000 H=011A S=0100 

C0Z0M0E0I1 A=02 B=0700 D=0000 H=011A S=0100 

C0Z0M0EOI1 A=00 B=0000 D = 0000 H=0119 S=0100 

— U5 Trace without listing intermediate states 

C0Z0M0E1I1 A=00 B=0700 D=0000 H=011A S=0100 P=0109 JNC 010D*0108 
-X CPU State at end of U5 

C0Z0M0E1I1 A=04 B=0600 D=0000 H=011B S=0100 P=0108 SUB C 

~ - Run program from current PC until completion tin real-time) 

breakpoint at 116H. caused by executing RST 7 in machine code 

•0116 

—X CPU state at end of program 

C0Z1M0E1I1 A=00 B=0000 D=0000 H=0121 
— X.P examine and change program counter 



S=0100 P=0116 RST 07 



P=0116 100 



C0Z1M0E1I1 A=00 B=0000 D=0000 
— T10 Trace 10 (hexadecimal) steps 

. first data element 

B=0000 

B=080Q. 

B=p800 

=0800 

b =085(3; 



H=0121 S=0100 P=0100 MVI 




subtext tor comparison-^ 
current largest value 



B=0800 D=0000 



H=0121 ,-8-=0100 
H^OWf" S=0100 
=0121 S = 0100 
H=0119 S=0100 
H=0119 S = 0100 
H=0119 S=0100 



p= 


= 0100 


MVI 


B,08 


p= 


=0102 


MVI 


COO 


P= 


=0104 


LXI 


H.011 


p= 


=0107 


MOV 


A,M 


p= 


=0108 


SUB 


c— " 


p= 


=0109 


JNC 


010D 
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Insert a "hot patch" into 
0109 JC __10p the machine code 

to change the 
010C JNCtoJC 



Program should have moved the - 
value from A into C since A C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 



-GO 



Stop DDT so that a version of 

the patched program can be saved 



SAVE 1 SCAN.COM Program resides on first page, so save 1 page. 

A ■DD.T_S.QAN, COM Restart DDT with the saved memory image to continue testing 



16K 


DDT VER 1.0 


NEXT PC 




0200 


0100 




— L100 List some code 


0100 


MVI 


B.08 


0102 


MVI 


COO 


0104 


LXI 


H.0119 


0107 


MOV 


A.M /" 


0108 


SUB 


C J 


0109 


JC 


010D-^ 


010C 


MOV 


C.A 


010D 


INX 


H 


010E 


DCR 


B 


010F 


JNZ 


0107 


0112 


MOV 


AC 


-XP 






P=0100 





Previous patch is present in X-COM 



— T10 Trace to see how patched version operates 



Data is moved from A to C 



COZOMOEOIO 


A = 


= 00 


B 


=0000 


D 


= 0000 


H 


= 0000 


S 


= 0100 


p 


= 0100 


MVI 


B.08 


COZOMOEOIO 


A = 


= 00 


B 


=0800 


D 


= 0000 


H 


= 0000 


S 


--01 00 


p= 


= 0102 


MVI 


COO 


COZOMOEOIO 


A 


-00 


B 


-0800 


D 


0000 


H 


=0000 


S 


0100 


P 


0104 


LXI 


H.0119 


COZOMOEOIO 


A 


-00 


B 


0800 


D 


= 0000 


H 


J3119 


S 


= 0100 


P 


=0107 


MOV 


A.M 


COZOMOEOIO 


A = 


=@) 


B = 


= 0800 


D = 


=0000. 


„-H 


= 0119 


S 


= 0100 


P= 


=0108 


SUB 


C 


C0Z0M0E0I1 


A = 


=02 




= 0800 


D = 


=ooot> 


H 


= 0119 


s- 


= 0100 


P= 


=0109 


JC 


010D 


C0Z0M0E0I1 


A = 


= 02 


B = 


=«£S00 


,0===OOOO 


H 


= 0119 


S- 


0100 


p 


010C 


MOV 


C A 


C0Z0M0E0I1 


A 


02 


B 


= 08@^ 


D- 


0000 


H 


-0119 


S 


0100 


p 


-010D 


INX 


H 


C0Z0M0E0I1 


A 


= 02 


B 


0802 


D 


0000 


H 


01 1A 


S 


= 0100 


p= 


= 010E 


DCR 


B 


COZ0MOEOI1 


A = 


=02 


B = 


=0702 


D = 


= 0000 


H 


= 011A 


S = 


= 0100 


P- 


-010F 


JNZ 


0107 


C0Z0M0E0I1 


A = 


= 02 


B = 


=0702 


D = 


= 0000 


H- 


= 011A 


S = 


-0100 


p 


0107 


MOV 


A.M 


C0Z0M0E0I1 


A = 


= 00 


B = 


= 0702 


D = 


= 0000 


H = 


=011A 


S 


0100 


p 


0108 


SUB 


C 


C1Z0M1E0I0 


A = 


= FE 


B = 


= 0702 


D 


0000 


H 


= 011A 


S = 


= 0100 


p= 


= 0109 


JC 


010D 


C1Z0M1E0I0 


A = 


= FE 


B = 


= 0702 


D- 


= 0000 


H 


= 011A 


S = 


=0100 


p= 


= 010D 


INX 


H 


C1Z0M1E0I0 


A = 


= FE 


B = 


= 0702 


D = 


=0000 


H = 


= 011B 


S 


0100 


p 


010E 


DCR 


B 


C1Z0M0E1I1 


A 


FE 


B 


0602 


D = 


^0000 


H- 


011B 


S 


= 0100 


p= 


= 010F 


JNZ 


0107'010 


-X 






















breakpoint after 16 steps -J 



C1Z0M0E1I1 A-FE B = 0602 D = 0000 H-011B S"0100 P~0107 MOV AM 
— G.108 Run from current PC and breakpoint at 108H 
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*0108 
-X 



r 



next data item 



C1Z0M0E1I1 A=04 B=0602 D=0000 H=011B S=0100 P=0108 SUB C 
~ - Single step for a few cycles 

C1Z0M0E1I1 A=04 B = 0602 D=0000 H=011B S=0100 P = 0108 SUB O0109 
-T 

COZ0MOEOI1 A=02 B=0602 D = 0000 H=011B S = 0!00 P=0109 JC 010D-010C 
-X 

COZOM0EOI1 A=02 B=0602 D=0000 H=011B S = 0100 P=010C MOV C.A 
— G Run to completion 

"0116 
-X 

C0Z1M0E1I1 A=03 B=0003 D=0000 H=0121 S=0100 P = 0116 RST 07 
-S121 look at the value of LARGE 

0121 03 Wrong Value! 

0122 00 

0123 22 

0124 21 

0125 00 

0126 02 

0127 7E 



End of the S command 



0100 MVI B,08 

0102 MVI COO 

0104 LXI H.0119 

0107 MOV A,M 

0108 SUB C 

0109 JC 01 OD 
010C MOV C.A 
010D INX H 
010E DCR B 
010F JNZ 0107 

0112 MOV A,C 
-L 

0113 STA 0121 

0116 RST 07 

0117 NOP 

0118 NOP 

0119 STAX B 
011 A NOP 
011B INR B 
011C INX B 
01 1D DCR B 
01 1E MVI B,01 

0120 DCR B 
-XP 



P=0116 100 Reset the PC 



Review the code 



— T Single step, and watch data values 

C0Z1M0E1I1 A=03 B=0003 D=0000 H=0121 S=0100 P=0100 
-T 

C0Z1M0E1I1 A=03 B=0803 D=0000 H=0121 S=0100 P=0102 
— T .count set 

( ^^^' largest" set 
C0Z1M0E1I1 A=03 B=0800 D=0000 H=0121 S=0100 P=0104 
-T 

f base address of data set 
C0Z1M0E1I1 A=03 B=0800 D=0000 H=0119 S=0100 P=0107 
-T 

r first data item brought to A 
C0Z1M0E1I1 A=02 B=0800 D=0000 H=0119 S=0100 P=0108 
-T 

C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S=0100 P=0109 
-T 

COZOMOEOM A=02 B=0800 D=0000 H=0119 S=0100 P=010C 
-T 

f first data item moved to C correctly 
COZOMOEOM A=02 B=0802 D=0000 H=0119 S=0100 P=010D 
-T 

COZOMOEOM A=02 B=0802 D=0000 H=011A S=0100 P=010E 
-T 

COZOMOEOM A=02 B=0702 D=0000 H=011A S=0100 P=010F 
-T 

COZOMOEOM A=02 B=0702 D=0000 H = 011A S=0100 P=0107 
-T 

^- second data item brought to A 
COZOMOEOM A=00 B=0702 D=0000 H=011A S=0100 P=0108 
-T 

f- subtract destroys data value which was loaded!!! 
C1Z0M1E0I0 A=FE B=0702 D=0000 H=011A S=0100 P=0109 
-T 

C1Z0M1E0I0 A=FE B = 0702 D=0000 H=011A S=0100 P=010D 
- L100 

0100 MVI B,08 

0102 MVI COO 

0104 LXI H.0119 

0107 MOV A.M 

0108 SUB C- — 

0109 JC 01 OD 
01 OC MOV C.A 
010D INX H 
01 OE DCR B 
010F JNZ 0107 
0112 MOV A,C 
-A108 

0108 CMP C hot patch at 108H changes SUB to CMP 

0109 

-GO stop DDT for SAVE 

SAVE 1 SCAN.COM 

Save memory image 
A>DDT SCAN. COM Restart DDT 

16K DDT VER 1.0 
NEXT PC 
0200 0100 



MVI B.08*0102 

MVI C,00*0104 

LXI H,0119«0107 

MOV A,M*0108 

SUB C*0109 

JC 010D*010C 

MOV C.A*010D 

INX H>010E 

DCR B'OIOF 

JNZ 0107«0107 

MOV A.M*0108 

SUB C*0109 

JC 010D«010D 

INX H*010E 



- This should have been a CMP so that register A 
would not be destroyed 
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-XP 

P=0100 
-L116 

0116 RST 

0117 NOP 

0118 NOP 

0119 STAX B 
011A NOP 

— (rubout) 



07 



Look at code to see it it was properly loaded 
llong typeout aborted with rubout) 



- G . 1 1 6 Run from 100H to completion 

•0116 

— XC Look at Carry (accidental typo) 



C1 



Look at CPU state 



C1Z1M0E1I1 A=06 B = 0006 D=0000 H=0121 S=0100 P=0116 RST 07 
— S121 Look at "Large" — it appears to be correct. 



0121 


06 






0122 


00 






0123 


22 






-GO 


stop DDT 






ED 


SCAN. ASM 


Re-edit the source program, and make both changes 


•NSUB tl _ z 

*olt r 

SUB ' C 
•SSUBCZCMPfgOLT 

CMP C 


; LARGER VALUE IN C? 
; LARGER VALUE IN C? 


*SNC 


fzfc(4)0LT 


NFOUND 
NFOUND 


; JUMP IF LARGER VALUE NOT FOUND 


*E 


JC 


; JUMP IF LARGER VALUE NOT FOUND 



ASM SCAN.AAZ Re-assemble, selecting source from disk A 

hex to disk A 
CP/M ASSEMBLER - VER 1 .0 print to Zfselects no print tile) 

0122 

002 H USE FACTOR 

END OF ASSEMBLY 

DDT SCAN. HEX Rerun debugger to check changes 

16K DDT VER 1.0 
NEXT PC 
0121 0000 
-L116 



0116 JMP 0000 
0119 STAX B 
011 A NOP 
011B INR B 
— (rubout! 



check to ensure end is still at 11 6H 
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— G100.116 Go from beginning with breakpoint at end 

•0116 breakpoint reached 
-D121 Look at "LARGE" 

^ correct value computed 

0121 66Tocf"22 21 00 02 7E EB 77 13 23 EB OB 78 B1 ..' 
0130 C2 27 01 C3 03 29 00 00 00 00 00 00 00 00 00 00. 
0140 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 



— (rubout) aborts long typeout 

—GO stop DDT, debug session complete 
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Index 



A (append) 98 
A (Assemble) 150 
ASM 

arithmetic operators 123 

assembler directives 126 

command 23 

DB 131 

DS 132 

DW 131 

END 127 

ENDIF 129 

EQU 127 

error messages 139 

file type 52 

IF 129 

labels 120 

logical operators 123 

numeric constants 121 

operation codes 132 

ORG 126 

overview 116 

program format 118 

reserved words 1 22 

sample session 140 

SET 128 

string constants 123 



B 

B (block mode transfer) 
BAK file type 52 



BAS file type 52 

BAT: 23 

BDOS 3 

BDOS error messages 43 

BIOS 3,46 

BIOS call conventions 50 

BOOT 49 

Built-in commands 

DIR 12 

ERA 11 

overview 10 

REN 13 

SAVE 14 

TYPE 14 

USER 15 



33 



Call conventions (BIOS) 

CCP (Console Command 
Processor) 4, 46 

Close file 64 

COM file 52 

Compute file size 76 

CON: 22 

Console input 57 

Console output 57 

Context editor 94 

Control characters 16 

CP/M 
built-in commands 10 
disk parameter block f 



46 
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CP/M (continued) 

file references 7 

file types 52 

general command structure 7 

line editing 15 

logical divisions 3 

transient commands 17 
Currently logged drive 10 

D 

D (delete) 33 

DB 131 

DDT (Dynamic Debugging Tool) 

A (Assemble) 150 

command list 149 

D (Display) 150 

F(Fill) 151 

G (Go) 152 

I (Input) 153 

implementation 158 

L (List) 153 

M(Move) 154 

overview 149 

R(Read) 154 

S(Set) 155 

T (Trace) 156 

U(Untrace) 157 

X (Examine) 157 
Delete file 65 
DIR (directory) 12 
direct console I/O 58 
DS 132 
DUMP 43 
DW 131 



E (echo) 33 

ED 
command strings 102 
command summary 110 
control characters 109 
errors 108 
memory buffer 99 
operation 95 



ED (continued) 

overview 95 

repetitive commands 107 

source libraries 107 

text alteration 103 

text editing 111 

text search 103 

text transfer 95 
END 127 
ENDIF 129 
EOF: 31 
EQU 127 
Error messages 

ASM 139 

BDOS 43 

ED 108 

F 

F (filter) 33 

FDOS 46, 50 

file control block 53 

file reference 7 

file types 52 

G 

G (get file) 34 

Get address (allocation) 70 

Get address (disk parameters) 72 

Get console status 61 

Get I/O Byte 59 

Get Read/Only vector 71 

Get user code 72 

General command structure 7 



H 

H (hex data transfer) 
Hex files 52 



34 



/ 



34 



I (ignore) 
IF 129 
INP: 31 
INT file type 
Intel 8080 2 



J 




Jump codes 
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L 




L (translate) 


34 


Line editing commands 15 


List devices 


23 


List output 


58 


LOAD 26 




Logical devices 22 


LPT: 23 




LST: 23 





M 

Makefile 67 

Memory buffer organization 97 

Memory organization (CP/M) 47 

N 

N (add line numbers) 34 
NUL: 31 

o 

O (object file transfer) 34 

Open file 63 

Operand 120 

Operation codes 132 

ORG 126 

OUT: 31 

Output Control 15 



P (include page ejects) 34 

PIP 27 

Physical devices 23 

Print string 59 

PRN: 31 

PTP: 23 

PTR: 23 

PUN: 23 

Punch output 58 



52 





Q (quit copying) 



34 



R 

R (read system files) 35 
RDR: 23 

Read console buffer 60 
Read random 73 
Read sequential 66 
Reader input 57 
REL file 52 
REN(REName) 13 
Reset disk system 62 
Return current disk 69 
Return login vector 68 
Return version number 61 



S (start copying) 35 

Sample programs 
file dump utility 81 
file-to-file copy program 78 
random access program 84 

SAVE 14 

Search for First 64 

Search for Next 65 

Select disk 62 

SET 128 

Set DMA address 69 

Set file attributes 71 

Set I/O Byte 59 

Set random record 77 

Set user code 72 

Special characters 8 

STAT 1 8 

SUBMIT 40 

SYM file 52 

System function summary 92 



T (expand tabs) 35 
Text transfer operations 95 
Transient commands 17 
TTY: 23 
TYPE 14 
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U 

U (all uppercase) 35 

UC1: 23 

UL1: 23 

UP1: 23 

UP2: 23 

UR1: 23 

UR2: 23 

USER 15 



V (verify) 35 
VAL 24 

w 

W (write over R/O) 35 
Write protect disk 70 
Write random 75 
Write sequential 66 

X 

XSUB 42 



Z (zero parity bit on input) 
Zilog Z-80 2 



35 



